API接口设计规范：RESTful架构与安全认证实战

系统越来越多，数据却各自为政——这是很多企业信息化建设中的常见问题。官网的询盘数据在一个库里，CRM的客户数据在另一个库里，财务系统又是一套独立的数据。

把这些系统打通，靠的就是API接口。API（Application Programming Interface）是系统之间通信的桥梁，设计得好，数据流转顺畅；设计得差，维护起来就是噩梦。

RESTful API设计原则

REST（Representational State Transfer）是目前应用范围广泛的API设计风格。它的核心原则是：

资源导向

URL代表资源，用名词而不是动词：

• GET /api/v1/customers — 获取客户列表
• GET /api/v1/customers/123 — 获取ID为123的客户
• POST /api/v1/customers — 新增客户
• PUT /api/v1/customers/123 — 更新客户信息
• DELETE /api/v1/customers/123 — 删除客户

不要写成 /api/getCustomerList 或 /api/deleteCustomer?id=123，那是RPC风格，不是REST。

合理使用HTTP状态码

不要所有请求都返回200，然后在body里放错误码。正确的做法是用HTTP状态码表达结果：

• 200 OK — 请求成功
• 201 Created — 资源创建成功
• 400 Bad Request — 请求参数错误
• 401 Unauthorized — 未认证
• 403 Forbidden — 无权限
• 404 Not Found — 资源不存在
• 500 Internal Server Error — 服务端异常

版本管理

API一旦上线，就可能有多个客户端在调用。改了接口格式，老版本的App就崩了。所以要做版本管理：

• URL路径方式：/api/v1/customers、/api/v2/customers
• Header方式：Accept: application/vnd.myapp.v2+json

路径方式更直观，大多数项目选这种。

分页与过滤

列表接口一定要支持分页，不要一次返回全部数据：

• GET /api/v1/customers?page=1&size=20 — 分页
• GET /api/v1/customers?status=active&sort=created_at:desc — 过滤和排序

安全认证方案

API安全是重中之重，尤其是涉及业务数据的接口。

Token认证

目前主流的方案是JWT（JSON Web Token）：

1. 客户端用账号密码调用登录接口
2. 服务端验证通过后返回一个JWT Token
3. 后续请求在Header里带上 Authorization: Bearer <token>
4. 服务端验证Token的签名和有效期

JWT的好处是无状态，服务端不需要存Session，适合分布式部署。

API Key认证

适合系统间对接（B2B场景）。给每个对接方分配一个API Key和Secret，请求时带上Key，用Secret对参数签名。服务端验证签名是否匹配。

OAuth 2.0

适合第三方授权场景，比如"用微信登录"。流程相对复杂，但安全性高，适合开放平台。

安全加固措施

除了认证，还需要这些安全措施：

• HTTPS：所有API必须走HTTPS，防止数据被窃听
• 限流：单个IP或Token在一定时间内的请求次数限制，防止暴力攻击和爬虫
• 参数校验：所有输入参数都要校验类型、长度和范围，防止注入攻击
• 日志记录：记录每次API调用的来源、参数和结果，方便审计和排查问题
• 敏感数据脱敏：手机号、身份证号等敏感字段在返回时做部分遮盖

常见的设计误区

误区一：接口粒度太细

把每个字段的增删改查都做成独立接口，导致一个页面要调十几个接口。应该按业务场景聚合，一个接口返回页面需要的全部数据。

误区二：没有统一的响应格式

有的接口返回 {code: 0, data: {...}}，有的返回 {success: true, result: {...}}。同一个项目里格式不统一，前端对接很痛苦。

建议统一为：

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

误区三：不写文档

"代码就是文档"是自欺欺人。API文档要清楚写明每个接口的URL、请求方式、参数说明、返回格式和错误码。推荐用Swagger/OpenAPI自动生成文档，和代码保持同步。

误区四：不做版本管理就上线

先上线再说，改了接口格式发个通知让大家改——这在多系统对接时会引发连锁故障。

写在最后

API设计看似简单，但细节很多。一套规范的API体系，能让系统间的对接效率提升数倍，也能大幅降低后期维护成本。企业在选择软件开发服务商时，可以从API设计规范这个角度来评估团队的技术水平——一个连接口文档都写不清楚的团队，系统质量大概率也堪忧。