Python函数JSON参数的类型注解方案及文档规范咨询

一、类型注解：别用Any，拆分复杂结构更清晰 #

直接用typing.Any等于放弃了类型检查的核心价值，完全失去注解的意义。你可以用TypedDict把嵌套结构拆分成多个小的类型定义，让注解既严谨又简洁，可读性大幅提升。

比如针对你描述的「列表嵌套字典、字典内再嵌套字典」的结构，可拆分定义如下：

from typing import TypedDict, List, Union

# 定义内层嵌套的字典类型
class OrderItem(TypedDict):
    item_id: str
    item_name: str
    quantity: int
    is_in_stock: bool

# 定义外层的订单字典类型
class Order(TypedDict):
    order_id: str
    user_id: Union[str, int]
    create_time: str
    items: List[OrderItem]
    note: Union[str, None]

# 最终函数的参数注解就非常简洁
def get_order_list(orders: List[Order]) -> List[str]:
    # 函数逻辑：提取所有订单ID
    return [order["order_id"] for order in orders]

拆分后每个层级的结构清晰可见，mypy、PyCharm等类型检查工具能准确校验参数是否合规。如果结构中有更多可选类型，Python 3.10+还可以用|替代Union，语法更简洁。

至于json.loads的返回类型，你可以直接将其注解为自己定义的结构——虽然json.loads本身返回Any，但你明确知道解析后的结果符合预期结构，这样注解合理且能让类型检查正常工作：

import json

raw_json = '[{"order_id": "OD123", ...}]'
parsed_orders: List[Order] = json.loads(raw_json)
get_order_list(parsed_orders)

二、JSON结构的文档：优先写在函数文档字符串里 #

必须编写文档，因为嵌套结构仅靠类型注解无法覆盖所有细节（比如字段的取值范围、必填/可选规则）。

• 优先选择函数文档字符串：调用者查看函数时能直接获取输入结构的完整说明，建议搭配示例JSON片段展示：

  def get_order_list(orders: List[Order]) -> List[str]:
      """
      从订单列表中提取所有订单ID
  
      参数:
          orders: 符合指定结构的订单列表，单条订单结构示例：
              {
                  "order_id": "字符串类型的唯一订单ID",
                  "user_id": "用户ID，支持字符串或整数类型",
                  "create_time": "订单创建时间，格式为YYYY-MM-DD HH:MM:SS",
                  "items": [
                      {
                          "item_id": "商品ID",
                          "item_name": "商品名称",
                          "quantity": "购买数量（正整数）",
                          "is_in_stock": "商品是否有货（布尔值）"
                      }
                  ],
                  "note": "可选字段，订单备注（字符串或null）"
              }
  
      返回:
          所有订单的ID组成的列表
      """
      return [order["order_id"] for order in orders]
  

• 如果该JSON结构被多个函数复用，或者结构异常复杂，可以把通用说明放在文件级别的文档字符串里，再在函数文档中引用该结构。

• 非大型项目无需单独写文档文件，否则会增加维护成本，调用者也难以快速找到对应说明。

内容的提问来源于stack exchange，提问作者Eutropios