API 设计安全规范

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));