Python函数中NDJSON/JSON的类型提示方案咨询

API 探路者

2026-8-20

Python中NDJSON的类型提示方案

可选的类型提示方式：

直接使用str类型
NDJSON本质就是换行分隔的JSON字符串，最直接的方式就是用标准的str作为类型提示，示例代码如下：

import json
from typing import List, Dict

def get_ndjson(employees_dicts_list: List[Dict[str, str | int]]) -> str:
    employee_data = [json.dumps(employee) for employee in employees_dicts_list]
    return "\n".join(employee_data)

这种方式无需额外依赖，Python标准库完全支持，简单直接。

自定义类型别名
如果想让类型提示更具语义可读性，可以用typing.TypeAlias定义一个NDJSON别名：
```
from typing import TypeAlias, List, Dict
import json

NDJSON: TypeAlias = str

def get_ndjson(employees_dicts_list: List[Dict[str, str | int]]) -> NDJSON:
    employee_data = [json.dumps(employee) for employee in employees_dicts_list]
    return "\n".join(employee_data)
```
这里NDJSON本质还是str，但能直观表达变量的语义，不会影响类型检查工具的判断，是平衡实用性和可读性的最优方案。
用NewType创建严格语义类型
若需要类型检查工具将NDJSON与普通字符串严格区分开，可以使用typing.NewType：
```
from typing import NewType, List, Dict
import json

NDJSON = NewType("NDJSON", str)

def get_ndjson(employees_dicts_list: List[Dict[str, str | int]]) -> NDJSON:
    employee_data = [json.dumps(employee) for employee in employees_dicts_list]
    return NDJSON("\n".join(employee_data))
```
这种方式需要显式将字符串包装为NDJSON类型，类型检查时会认为它和普通str是不同类型，适合对语义区分要求极高的场景。