写 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
📝 文档：Swagger/OpenAPI 自动生成
写完代码顺手加注解，用 Swagger UI 或 Knife4j 自动生成交互式文档，前端对着文档联调不扯皮。 别用 Word 写接口文档，发布后第二天就过时。
⚠️ 避坑铁律
别用 GET 传密码(URL 会记日志)，敏感数据走 POST+HTTPS;别把异常堆栈直接返前端，给用户看“系统繁忙”就行，日志里记详细;接口粒度别太细(一个页面调 20 个接口)也别太粗(一次返回 500 字段)，按前端场景聚合;版本升级先兼容旧版，给调用方迁移时间;参数校验别信前端，服务端必须再验一遍。
