API接口怎么写？RESTful设计规范与请求响应鉴权咋走不串RPC？

2026-08-28 17:23:02 美源教育

写 API 接口不是“把数据库查询结果返回给前端”就完事，而是一套资源建模、协议约定、安全鉴权、文档交付的工程化动作。主流走 RESTful 风格(HTTP+JSON)，别和 RPC(远程过程调用，如 gRPC/Dubbo)混——REST 面向资源，RPC 面向动作，选型先定调。

📐 设计：RESTful 五条铁律

用名词不用动词：GET /users(取用户列表)✅，GET /getUsers ❌;

HTTP 动词表操作：GET 查、POST 增、PUT 全量改、PATCH 部分改、DELETE 删;

状态码语义化：200 成功、201 创建成功、400 参数错、401 未登录、403 无权限、404 资源不在、500 服务器炸;

版本控制放 URL 或 Header：/api/v1/users，别让 v2 把 v1 用户搞崩;

过滤/分页/排序：GET /users?page=2&size=20&sort=created_at,desc，别把所有数据一把梭。

⚙️ 实现：请求→处理→响应

请求：客户端发 JSON(如 {"name":"张三","age":25})，服务端用框架(Spring Boot/Express/FastAPI/Django REST Framework)反序列化、校验字段;

处理：调业务逻辑、访数据库、做事务，别在 Controller 里写 SQL;

响应：统一格式 {"code":0,"msg":"success","data":{...}}，错误时 code 非 0、msg 给人看、data 可为空;分页响应包 total/page/pages/records。

🔐 鉴权：JWT 是当前标配

登录接口校验账号密码，成功后返回 access_token(JWT)，客户端后续请求放 Header Authorization: Bearer ;服务端验签名、读 payload(用户ID/角色/过期时间)，不查库也能鉴权。刷新 token 用 refresh_token 换 access_token，别让 access_token 有效期太长。 OAuth2 适合第三方授权(微信登录)，简单内部系统 JWT 足够。

📝 文档：Swagger/OpenAPI 自动生成

写完代码顺手加注解，用 Swagger UI 或 Knife4j 自动生成交互式文档，前端对着文档联调不扯皮。别用 Word 写接口文档，发布后第二天就过时。

⚠️ 避坑铁律

别用 GET 传密码(URL 会记日志)，敏感数据走 POST+HTTPS;别把异常堆栈直接返前端，给用户看“系统繁忙”就行，日志里记详细;接口粒度别太细(一个页面调 20 个接口)也别太粗(一次返回 500 字段)，按前端场景聚合;版本升级先兼容旧版，给调用方迁移时间;参数校验别信前端，服务端必须再验一遍。