API 设计安全规范

当设计或修改 REST API 响应结构时，防止常见的设计缺陷。

---

陷阱 #1: 泛型方法重载歧义

场景: 返回类型为 String 时，Java 重载解析可能匹配错误的方法

问题根因

Java 方法重载解析时，String 类型参数会优先匹配 success(String message) 而非 success(T data)，导致数据进入错误的字段。

错误示例

// ApiResponse 有两个重载:
public static <T> ApiResponse<T> success(T data)
public static <T> ApiResponse<T> success(String message, T data)

// ❌ 错误: String 类型匹配到 success(String message)
String avatarUrl = "http://example.com/avatar.jpg";
return ApiResponse.success(avatarUrl);
// 结果: {"code":200, "message":"http://...", "data":null}
// 前端 data.data 拿到 null，导致功能异常

正确做法

// ✅ 方案1: 明确指定 message 参数（推荐）
return ApiResponse.success("上传成功", avatarUrl);
// 结果: {"code":200, "message":"上传成功", "data":"http://..."}

// ✅ 方案2: 使用泛型明确类型
return ApiResponse.<String>success(avatarUrl);

// ✅ 方案3: 包装为 DTO（复杂场景推荐）
return ApiResponse.success(new UploadResult(avatarUrl));

检查清单

• 返回 String 类型时，是否明确指定 message 参数
• 是否有单参数和双参数的重载方法
• 前端是否正确解析 data 字段（而非 message）
• 是否有单元测试验证响应结构

---

陷阱 #2: 响应字段语义不清

场景: message 和 data 字段职责混淆

规范

字段	用途	类型	示例
code	业务状态码	int	200, 400, 500
message	用户可读的提示信息	String	"上传成功", "参数错误"
data	业务数据	T	{"url": "..."}, [...]
timestamp	响应时间戳	String	ISO 8601 格式

错误示例

// ❌ 错误: 把业务数据放在 message
return ApiResponse.success("avatars/2026-04/xxx.jpeg");

// ❌ 错误: message 包含技术细节
return ApiResponse.error("NullPointerException at line 42");

正确做法

// ✅ message 是用户提示，data 是业务数据
return ApiResponse.success("上传成功", avatarUrl);

// ✅ 错误信息对用户友好
return ApiResponse.error("文件格式不支持，请上传 JPG/PNG 格式");

---

陷阱 #3: 空值处理不一致

场景: 无数据时返回 null、{}、[] 不统一

规范

场景	推荐返回	说明
单个对象不存在	data: null	前端判断 if (!data)
列表为空	data: []	前端可直接遍历
分页数据为空	data: {list: [], total: 0}	保持结构一致

错误示例