很多人第一次写接口时会把重点放在“能不能返回数据”。只要前端能调通页面能显示就觉得接口设计完成了。但接口不是临时函数。它是前端、后端、数据库、权限、错误处理和未来扩展之间的契约。一开始设计得太随意后面每次改功能都会变成连锁反应。第一个接口不需要复杂但一定要清楚、稳定、可理解。先明确接口服务什么动作写接口前不要先想 URL而要先想用户动作。用户是在创建项目、获取列表、更新设置、上传文件、提交订单还是查看结果接口应该服务一个明确动作不要把多个不相关的动作塞进同一个接口。比如“创建项目”和“修改项目设置”应该是两个接口“获取项目列表”和“获取项目详情”也应该分开。接口越清楚前端越容易使用后端越容易维护问题也越容易排查。用资源而不是动词组织路径常见的新手写法是/api/createProject /api/getProjectList /api/updateProject /api/deleteProject这种写法能用但长期会变乱。更推荐用资源路径加 HTTP 方法表达动作GET /api/projects POST /api/projects GET /api/projects/:id PATCH /api/projects/:id DELETE /api/projects/:id路径表示资源方法表示动作。这样接口结构更统一也更容易被别人理解。请求参数要分清位置接口请求参数通常有三类路径参数、查询参数和请求体。路径参数用于定位资源比如/api/projects/123里的123。查询参数用于筛选、搜索、排序和分页比如?statusactivepage1。请求体用于提交创建或更新的数据。不要把所有参数都塞进请求体也不要把复杂数据塞进 URL。一个清晰的规则是定位资源放路径控制列表放查询提交数据放请求体。响应结构要稳定接口返回给前端的数据结构要尽量稳定。不要今天返回数组明天返回对象成功时一个结构失败时另一个完全不相关的结构。一个常见的成功响应可以是{ data: { id: project_123, name: Demo Project, status: active } }列表响应可以包含分页信息{ data: [ { id: project_123, name: Demo Project } ], pagination: { page: 1, pageSize: 20, total: 128 } }稳定的响应结构会让前端少写很多特殊判断。错误响应要能帮助定位问题接口失败时不要只返回“失败”或“服务器错误”。错误响应至少要包含错误码、可读信息和必要的字段信息。比如{ error: { code: PROJECT_NAME_REQUIRED, message: Project name is required., field: name } }前端可以根据code做逻辑判断根据message展示提示根据field高亮表单字段。好的错误设计不只是为了开发者也是为了用户体验。输入必须校验不要相信前端传来的任何数据。即使前端已经限制了字段长度、格式和必填项后端仍然必须重新校验。因为接口可以被绕过用户也可以直接请求 API。校验至少包括必填字段、字段类型、长度限制、枚举值、数字范围、文件大小、权限范围、业务规则。输入校验越早越清楚后面的数据污染越少。鉴权和权限要分开看鉴权回答“你是谁”权限回答“你能不能做这件事”。很多新手只判断用户是否登录却忘了判断用户是否有权限操作某个资源。比如用户登录了不代表他能删除别人的项目团队成员能查看项目不代表他能修改账单普通用户能上传文件不代表他能访问管理员接口。每个涉及用户数据的接口都要同时考虑鉴权和权限。接口要考虑幂等性幂等性指同一个请求执行多次结果不会产生意外副作用。比如用户点击“保存设置”两次不应该生成两份设置支付回调收到两次不应该创建两张订单删除同一个资源多次不应该导致系统异常。不是所有接口都天然幂等但重要接口要提前设计。尤其是支付、订单、Webhook、后台任务、批量操作一定要考虑重复请求。列表接口要从一开始支持分页不要让列表接口一次返回所有数据。早期数据少时看不出问题后面数据一多接口会变慢页面会卡数据库压力会变大。列表接口应该从一开始支持分页、排序和必要筛选。即使当前只有几条数据也要保留结构。比如GET /api/projects?page1pageSize20statusactivesortcreatedAt_desc这会让未来扩展更自然。不要过早设计复杂版本号很多人第一次写 API 就开始设计/api/v1、/api/v2、复杂版本策略。如果你的 API 只服务自己的前端早期不一定需要复杂版本管理。更重要的是保持响应结构稳定避免随意破坏字段含义。如果你的 API 会开放给第三方或者会被多个客户端长期使用就需要更认真地设计版本、兼容策略和弃用流程。版本号不是越早越专业而是要看使用边界。文档要跟接口一起写接口文档不需要一开始很华丽但必须能说明接口做什么请求参数是什么响应是什么错误有哪些权限要求是什么。最简单的文档也可以是POST /api/projects 作用创建项目 权限登录用户 请求体name, description 成功返回项目详情 错误PROJECT_NAME_REQUIRED, PROJECT_LIMIT_EXCEEDED文档的价值不是形式而是减少沟通成本。半年后你自己也会感谢当时写清楚了。一个第一个接口模板你可以用下面模板设计接口接口名称 用户动作 资源对象 HTTP 方法 路径 路径参数 查询参数 请求体 权限要求 成功响应 错误响应 是否需要幂等 是否需要分页 是否需要日志每次写接口前先填这张表能避免很多随手设计。写在最后第一个接口的目标不是炫技而是建立稳定的契约。路径清楚、参数清楚、响应稳定、错误可读、权限明确、文档同步这些基础做好后面的功能才会越写越顺。下一篇我们继续聊接口和外部系统Webhook 实战。原文链接第一个接口怎么设计 | Harries Blog™