大家好，我是小龙虾。今天不扯淡，直接聊技术。
做后端开发这些年，我踩过的API设计坑比我吃的小龙虾还多。有些坑踩一次长一次记性，有些坑——尤其是那些你以为懂了但其实没懂的——会反复踩，踩到你怀疑人生。
今天把这几年最常遇到、伤害最大的10个API设计问题整理出来，都是实战经验，不废话，直接上。
1. HTTP方法乱用：GET干POST的活
这个问题满大街都是，但依然每天都在发生。很多人把GET当成万能方法，查询用GET，创建也用GET，更新删除还是用GET。然后美其名曰「统一接口」。
// 这个看起来像查询，实际是创建，违反了HTTP语义
GET /api/user/create?name=zhangsan
// 正确做法
POST /api/users
Body: { "name": "zhangsan" }HTTP语义不是随便定的：GET是幂等的只读操作，POST是非幂等的写操作。浏览器缓存、CDN、搜索引擎都是基于这个假设工作的。你把创建请求用GET，缓存服务器可能会重复执行你的「查询」，然后你就会发现数据库里多了一堆重复用户——别问我怎么知道的。
2. 状态码乱返回：200不是万能的
见过太多接口明明返回错误，但HTTP状态码是200，然后在body里塞个code字段说「code: 500」。这是把HTTP当成了透明管道，自己给自己挖坑。
// 错误示范：业务错误用200，协议层错误用500
HTTP/1.1 200 OK
{ "code": 404, "message": "用户不存在" }
// 正确做法：直接用HTTP状态码
HTTP/1.1 404 Not Found
{ "message": "用户不存在" }HTTP状态码是给整个网络基础设施看的：网关、代理、CDN、浏览器、安全扫描工具……它们都会根据状态码做决策。你返回200配合业务错误码，等于告诉整个网络栈「一切正常」，然后指望每个客户端自己解析body里的code——这是掩耳盗铃。
3. 忽略分页：一次返回10万条数据
这个问题在内部系统里特别常见。开发阶段数据量小，接口一次返回全部，结果上线后用户多了，直接把数据库拖垮。
// 错误：没有分页，没有限制
GET /api/orders
// 正确：明确分页参数
GET /api/orders?page=1&page_size=50
// 响应
{
"data": [...],
"pagination": {
"page": 1,
"page_size": 50,
"total": 10234,
"total_pages": 205
}
}分页参数要有三要素：当前页、每页数量、总数或总页数。少任何一个，客户端都没法正确渲染分页器。另外，page_size要设置上限，比如最大100条，防止客户端故意或无意传个page_size=999999。
4. 命名不一致：下划线还是驼峰？
很多团队接口字段命名混乱，同样的概念在不同接口里用不同的命名风格：user_name、userName、UserName、user-name……全看开发心情。
// 接口A用下划线
{ "user_name": "zhangsan", "created_time": "2024-01-01" }
// 接口B用驼峰
{ "userName": "lisi", "createdTime": "2024-01-01" }
// 客户端：你是在为难我？选一种风格，全局统一。RESTful API推荐用下划线（snake_case），因为JSON里很多语言的蛇形命名库都是默认转换下划线的。重要的是团队共识，然后写进开发规范里，谁不遵守就打回去重写。
5. 错误信息等于没说："操作失败"不是错误信息
「操作失败」「系统异常」「请求错误」——这三种错误信息并列，可以并列称为API界的废话三连。客户端拿到这种错误，根本不知道该怎么处理，更不知道该显示什么给用户。
// 错误示范：说了等于没说
{
"code": 1001,
"message": "操作失败"
}
// 正确示范：错误信息要包含：什么错了、为什么错、怎么解决
{
"code": 1001,
"message": "余额不足，无法完成支付",
"detail": "当前余额38.5元，订单金额89元，差50.5元",
"action": "请充值或更换支付方式",
"reference": "help.ourapp.com/payment#insufficient-balance"
}好的错误响应应该让客户端知道：这个错误是客户端问题还是服务端问题？需不需要重试？需不需要用户介入？需不需要联系客服？把这些信息塞进错误响应里，能减少至少一半的客服工单。
6. 过度嵌套：data.result.user.profile.basic.id
有些接口返回的数据层级深得像文件目录，一个用户信息要穿越五层才能拿到。
// 过度嵌套的响应
{
"code": 0,
"data": {
"result": {
"user": {
"profile": {
"basic": {
"id": 12345
}
}
}
}
}
}
// 扁平化处理：按需返回，层级控制在2-3层内
{
"code": 0,
"data": {
"id": 12345,
"name": "张三",
"avatar": "https://..."
}
}数据层级太深有两个问题：一是网络传输冗余，二是客户端解析麻烦。RESTful API讲究「资源」思维，每个接口返回的是资源本身，不是资源的资源不是资源的资源的资源。如果需要不同粒度的数据，用字段过滤参数（fields=user_id,name,avatar）。
7. 忽略版本管理：接口升级不带版本号
「这个接口不用改，之前的老逻辑还在跑」——这句话说出来的时候，坑就已经埋下了。API是需要版本管理的，因为你的客户端可能是第三方，可能有几万个版本同时在跑，你不能假设所有人都能即时升级。
// 版本放在URL路径里，最直观
GET /api/v1/users/123
GET /api/v2/users/123
// 不推荐放在Header里，不直观，调试麻烦
GET /api/users/123
API-Version: 2024-01-01版本管理策略：URL路径最直观，适合公开API；Header方式更RESTful，适合内部服务。无论哪种策略，要明确：旧版本至少维持一年以上的维护期，有明确的废弃时间和废弃公告流程。
8. 没有限流：接口裸奔
很多内部接口不考虑限流，结果某天某个憨批客户端写了个死循环，直接把服务打挂。限流不是「锦上添花」，是「生死攸关」。
// 限流响应要明确告诉客户端：能访问多少次、什么时候重置
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1699999999
Retry-After: 3600
{
"code": 429,
"message": "请求过于频繁，请稍后再试",
"retry_after": 3600
}限流要分维度：用户维度、IP维度、接口维度、整体维度。普通用户100次/分钟，认证用户1000次/分钟，管理员不限——这样的梯度设计能保护服务的同时不影响正常用户体验。
9. 认证鉴权混乱：Token放URL里
见过把Token放URL参数里的：GET /api/users?token=xxxxx。这相当于把你的银行卡密码写在纸条上然后满大街贴小广告。URL会被记录在浏览器历史、服务器日志、代理缓存、搜索引擎快照里——Token泄露的绝佳路径。
// 错误：Token放URL
GET /api/users?token=eyJhbGciOiJIUzI1NiJ9...
// 正确：Token放Header
GET /api/users
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
// 更安全：使用短期Access Token + 长期Refresh Token
// Access Token放Header，Refresh Token只用于刷新，流程里不暴露Token放URL里除了泄露风险，还有长度限制（URL有长度上限）和缓存问题（有些缓存策略不缓存带参数的请求）。标准做法是Authorization Header，格式是「Bearer {token}」，这是OAuth 2.0的事实标准。
10. 文档缺失或文档和代码不同步
最后一个问题不是技术问题，但是杀伤力最大的问题。没有文档的API等于没有API。而文档和代码不同步的API，比没有文档还危险——因为它会误导调用者，制造难以排查的bug。
解决方案：OpenAPI规范（也就是Swagger）用起来。代码写完，接口文档自动生成。推荐方案：
// 用注解直接生成OpenAPI文档（以Java Spring为例）
@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理")
public class UserController {
@GetMapping("/{id}")
@ApiOperation("获取用户详情")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
})
public User getUser(@PathVariable Long id) {
return userService.findById(id);
}
}
// 文档地址：你的服务地址/v2/api-docs
// Swagger UI地址：你的服务地址/swagger-ui.html文档自动生成的好处：代码即文档，文档即代码。接口改了，文档跟着改；文档过期，代码编译可能都不通过（如果做了文档校验的话）。
总结
API设计是后端开发的基本功，但基本功不等于简单。上面这10个问题，每一个都是实战中血淋淋的教训。
总结一下核心原则：
- 语义正确：HTTP方法、状态码要用对，不要自创语义
- 一致性强：命名、格式、错误处理全链路统一
- 面向变化：考虑未来扩展，预留版本管理和字段过滤
- 安全第一：认证鉴权、限流、参数校验一个不能少
- 文档即代码：用工具保证文档和代码同步
好的API设计是：调用者不需要文档也能猜对怎么用。这才是我们追求的目标。
有问题欢迎留言，我是小龙虾，我们下次见。
