按理说，

API 接口该不该返回 null？空值处理的常用方法

写接口的人觉得返回 null 天经地义。"没数据嘛，可不就是 null"。

调接口的人看到 null 就头大。每次取值都要先判空，一不小心就出现 Cannot read property of null。其实，

这两边的矛盾。本质上不是 null 对不对的问题，而是空值的语义没讲清楚。不过，

下面把踩出来的经验分成三块讲清楚：

• null 到底坑在哪；
• 不同类型该用哪种空值；
• Optional 怎么用才算用对了。说起来，

一、null 的真正问题：语义模糊。不是“空”

很多人以为 null 的争议在于“容易报空指针”，这只是表面。关键问题是 null 同时承载了三种含义调用方根本分不清你指的是哪一种：

实际情况	后端返回	调用方的理解
数据不存在	null	"没有" 还是 "未知"？
字段不适用	null	"没有" 还是 "未知"？
查询出错了	null	"没有" 还是 "出错"？说起来，

真实例子：使用者接口返回 {"address": null}前端拿到后完全不知道：

• 是这个使用者还没填地址？不过，
• 还是这个使用者类型本来就没有地址字段？
• 还是查询地址的服务挂了兜底返回了 null？

这三种情况前端的处理逻辑完全不同，却都被压缩成一个 null。这就是问题根源——null 是个语义黑洞.

链式调用更是灾难：

# 后端返回的接口数据
user_data = {
从"name"来看，"张三","address": None,# 这里返回了 null
"tags"的观点是。None # 这里也返回了 null
}
# 前端想取城市
city = user_data # TypeError: NoneType 不支持下标
# 想统计标签数量
count = len # TypeError: NoneType 没有 len

A single None/Null,every downstream usage must wrap with an If data is not None.... 代码膨胀、漏判一处就是 bug。null 把“防御”责任全部转嫁给调用方，却不给任何提示。不过，

二、不同类型。空值策略完全不一样

“一刀切”——全部返回 null 或全部返回空值，是偷懒。不同数据类型对应不同语义，我把实战中验证过的规则列出来：

. 字符串：默认用空串。除非要区分“未知”

默认返回 "",而不是 null. 下游拼接、长度判断、trim 都能直接使用，不必额外判空。

# 反面教材
def get_user_nickname:
user = db.find_user
return user.nickname if user else None # 返回 null
# 下游全是坑
nickname = get_user_nickname
display = "使用者：" + nickname # None 拼接 → "使用者：None"。丑且错
length = len # 报错

def get_user_nickname:
user = db.find_user
return user.nickname if user else "" # 返回空串
nickname = get_user_nickname
display = "使用者：" + nickname # 正常显示 “使用者：”
length = len # 正常计算

例外场景： 业务需要区分“未填”和“填了空”，如简历程序中的自我介绍，此时使用 null 表示未提供 .

. 数组 / 列表：永远返回空数组，绝不返回 null

# 列表字段永远返回，不要返回 null。

from dataclasses import dataclass,field
from typing import List
@dataclass
class UserVO:
name的观点是，str
tags的观点是，List = field # 默认空列表，不是 None
def list_users:
users = db.query_all_users
return # 防御性兜底：万一数据库返回 null，转成空列表
)
for u in users
]

The downstream can safely do ,len,tags.append. No need for any guard.

. 对象：用空对象或明确的不返回。别用 null 占位

• If field is optional → omit key entirely.
• If field must exist but may be empty → return an empty object {}.

# 反面教材：直接返回 None
def get_user_address:
addr = db.find_address
return addr.to_dict if addr else None
# 下游必须层层判空
data = get_user_address
city = data if data else ""
province = data if data else ""

A 娱乐ter approach – define defaults with Pydantic:

from pydantic import BaseModel
class AddressVO:
province: str = ""
从city来看，str = ""
district: str = ""
再看detail，str = ""
class UserVO:
name的观点是，str
address: AddressVO = AddressVO # 默认空对象
def get_user:
user = db.find_user
return UserVO(
name=user.name,address=AddressVO) if user.address else AddressVO
)

The downstream can directly access User.address.city​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​…​ without any guard.

. 数字：和 null 含义不同，别混淆

• "积分"、"登录次数"等计数类字段 → 用0表示「没有」而不是null。
• "上次登录时间戳"、"订单 ID" 等标识类字段 → 可以用null，但必须在文档里说明「null 表示从未」.

from typing import Optional
from datetime import datetime
from pydantic import BaseModel
class UserStatsVO:
login_count: int = 0 # 次数。用0表示「从未」
再看points，int = 0 # 积分，用0表示「无积分」
last_login_at: Optional = None # 时间戳，None 表示「从未登录」

三、Optional 不是装饰，是契约

Pythons 的 OptionalUnion它在类型层面告诉你「这个值可能为 T，也可能为 None」。其价值在于让调用方一眼看到需要处理空值的地方**。

. Optional 用在「可能没有」的地方，别滥用

If you mark every field as Optional,you lose contract – every consumer must still guard against None everywhere.

 from typing import Optional 

class OrderVO : orderid : str amount : float cancelreason : Optional ​​= ​​None ​​# 没取消就是 Null paid_at : Optional ​​= ​​None ​​# 未支付就是 Null

Calling code sees Optional and knows “handle possible Null”.

. 配合 mypy / Pydantic。让 Optional 真正发挥强制力

# pyproject.toml 开启严格模式
mypy --strict your_module.py 

def getusername -> Optional : user = db .find_user return user .name if user else None

name = getusername print )     # mypy 报错：item “None” of “Optional” has no attribute “upper”

mypy forces you to handle None before using value.

Pydantic 在序列化时自动把缺失字段设为 None而必填 str 则会校验失败，从而让模型本身成为接口契约。

. 完整 FastAPI 实战示例

 from typing import List,Optional
from datetime import datetime
from pydantic import BaseModel
from fastapi import FastAPI,HTTPException 

app ‑= FastAPI

# ---------- 响应模型 ---------- class AddressVO : province : str ‑= "" city       : str ‑= "" detail    : str ‑= ""

class UserVO : id               : int name             : str # 必填，不会是 Null nickname         : str ‑= "" # 默认 Empty string tags             : List ‑= # 默认 Empty list address          : AddressVO ‑= AddressVO # 默认 Empty object cancelreason    : Optional ‑= None # 可选字段。用 Optional 标记 lastlogin_at    : Optional ‑= None # 时间戳，可为 Null

# ---------- 接口 ---------- @app.get def getuser : user ⁼ db .finduser if not user : raise HTTPException

return UserVO ( id            ⁼ user .id,name          ⁼ user .name,# 必填 nickname  ⁼ user .nickname or "",# 空串兜底 tags    ⁼ user .tags or,# 空数组兜底 address⁠⁼ AddressVO if user .address else AddressVO,# 空对象兜底 cancelreason ⁼ user .cancelreason,# 允许 Null lastloginat ⁼ user .lastloginat # 允许 Null )

主要原则

1️⃣ 列表、字符串、嵌套对象 → 给默认 Empty 值，绝不返 null。2️⃣ “语义上可能不存在”的字段 → 用 Optional 明确标注，让调用方知道要判空。3️⃣ 整体资源不存在 → 用 HTTP 状态码 表达，而不是 { "data": null }。

四、痛点回顾与落地建议

• Pain Point 1： 线上白屏 / Crash。至于方法，统一把字符串/列表/对象设为空结构。
• Pain Point 2： 业务代码膨胀，导致维护成本高。至于方法，在后端统一做好 “防御式” 空值兜底，下游只写业务逻辑。
• Pain Point 3： 团队成员对 “null 是错误还是合法状态” 存疑，引发需求沟通成本。至于方法，在 OpenAPI / Pydantic 文档里明确每个字段是否 Optional 并写明语义。
• Pain Point 4： 静态检查缺失导致运行时 NPE 隐蔽出现。至于方法，开启 mypy 严格模式并配合 Pydantic。让类型程序强制执行 Empty‑Value 合约。说起来，
• Pain Point 5： 跨语言团队对 null/undefined 行为差异困惑。方法的观点是，统一 API contract —— Never return raw null for collection‑type fields；话说回来，使用语言无关的 “empty” 表达方式。
\end{ul}

只要后端遵循上述“Empty‑First”原则。并通过类型程序将可选性显式化，就能把原本散落在各个调用点的防御代码收敛到 API 层，实现真正意义上的“零负担”。"

---