如何对标准API响应类型的字典进行静态类型检查？

AI 小北

2026-6-29

解决方案

1. 启用严格的静态类型检查

用Pyright（VS Code默认集成，也可单独通过pip install pyright安装），在项目根目录创建pyrightconfig.json配置文件，开启严格检查模式：

{
  "strict": true,
  "typeCheckingMode": "strict"
}

2. 完善代码的类型标注

直接给视图函数标注返回类型为APIResponse，同时给响应变量添加类型注解——静态检查工具会自动验证字典结构是否符合TypedDict定义，不需要依赖运行时的assert_type：

from flask import Flask, jsonify
from typing import TypedDict, Union

app = Flask(__name__)

class APIResponse(TypedDict):
    success: bool
    data: Union[dict, list]

@app.get("/")
def index() -> APIResponse:
    response: APIResponse = {
        "success": True,
        "data": {"hello": "World!"}
    }
    return jsonify(response)

if __name__ == "__main__":
    app.run(debug=True)

3. 静态检查会自动捕捉错误

当你写出不符合规范的响应时，比如：

@app.get("/")
def index() -> APIResponse:
    response: APIResponse = {
        "success": "notABool",  # 静态检查报错：str类型不能赋值给bool类型
        "dat": {"hello", "World!"}  # 静态检查报错：键"dat"不在APIResponse定义中，且缺失必填键"data"
    }
    return jsonify(response)

Pyright会在IDE里直接标出这些问题，不用等到运行时才发现。

4. 进阶优化：封装响应生成函数

为了避免重复编写响应结构，封装一个生成规范响应的函数，通过类型标注从源头避免错误：

def create_api_response(success: bool, data: Union[dict, list]) -> APIResponse:
    return {"success": success, "data": data}

@app.get("/")
def index() -> APIResponse:
    return jsonify(create_api_response(True, {"hello": "World!"}))

如果传入错误类型的参数（比如给success传字符串），静态检查器会立刻报错。