路由与端点Route & Endpoint

你可能会说

用户访问不同的网址，怎么让不同的代码来接管？

路由决定访问一个网址或执行一种操作时，应交给后端的哪段功能处理。例如打开文章列表和提交一篇新文章，会交给两段不同功能处理。每个对外入口都要写清需要提供什么、成功后返回什么、失败时怎样说明。

先知道

也常被叫作路由EndpointAPI Endpoint接口端点

GET/api/posts→ 列表处理

POST/api/posts→ 创建处理

GET/api/posts/:id→ 详情处理

方法和路径一起决定进哪段代码

你可以这样告诉 AI Agent

请检查文章接口：GET /api/posts 负责读取列表，POST /api/posts 负责创建文章。分别写清输入、成功结果、失败状态和权限要求，并用实际请求验证两条端点没有混用。

用方法 + 名词路径表达意图：GET /users、POST /users

方法说明动作，路径说明对象

读取用户GET /users创建用户POST /users
把路径参数、查询参数和请求体分清楚

三种参数放在不同位置

路径/users/42查询?tab=orders请求体{ "name": "小林" }
每条端点写清输入、成功响应、错误状态和权限要求

一条端点要写清四件事

输入email成功201失败400 / 409权限需登录
先用浏览器 Network、curl 或 API 工具单独验证端点

先单独验证接口

curl -X POST /api/orders201 Created{ "orderId": "o_42" }

不要把所有功能放进一个含义不清的通用端点

一个端点包办一切

POST /api/doEverything{ "action": "maybe-save-or-delete" }

端点名称无法清楚表达其读取、修改或删除行为
读取数据却用 POST、删除数据却用 GET：会偏离 HTTP 语义，也可能影响缓存和安全预期

方法和动作相反

删除GET /delete/42读取POST /getUser
只设计成功响应：参数缺失、冲突和服务失败时也应返回约定的状态与错误信息

只设计成功分支

200 成功→500 失败→缺少恢复提示

参数缺失和服务失败也应有明确响应
把密码、令牌等敏感信息放在 URL 查询参数里：它们可能进入浏览历史和访问日志

敏感信息出现在网址里

GET /report?api_key=sk-live-••••浏览历史 · 访问日志 · 分享截图

组成结构 · Anatomy

GET/api/posts?page=2

GET 读取、POST 创建、PATCH 修改、DELETE 删除

资源地址，最好使用名词并保持复数规则一致

用于筛选、搜索、排序和分页，不应该包含密码或令牌

典型使用场景

GET /api/posts 取列表

文章列表GET /api/posts

请求参数?page=2&tag=design → 响应200 · 20 篇文章

POST /api/login 提交登录

提交登录POST /api/login

邮箱dev@ans.org密码••••••••登录

请求体携带账号信息，成功后建立会话

GET /api/users/:id 取详情

用户详情GET /api/users/:id

路径参数id = u_23姓名林小狐角色editor

DELETE /api/tasks/:id 删除任务

删除任务DELETE /api/tasks/:id

任务整理首页文案删除后按产品策略处理

确认删除

先确认，再请求 DELETE /api/tasks/t_42

A. GET /api/posts 读取，POST /api/posts 创建，并分别约定结果B. 所有功能都发到 /api/do，再让后端从一句文字里猜动作C. 读取和创建都使用 GET /api/posts，只改变请求体内容