[智能体-3]：RESTful 接口 超全详解（通俗易懂 + 实战规范）

一、基础概念1. 名词解释RESTRepresentational State Transfer表述性状态转移RESTful遵循 REST 设计风格的接口就是 RESTful API核心思想用 HTTP 标准方法对网络资源做增删改查2. 核心定位前后端分离、OpenAI API、大模型接口、所有互联网接口。主流设计规范统一格式、易读、易维护、跨语言通用二、RESTful 六大核心规范1. 一切皆「资源」互联网里所有数据都是资源必须是名词用户、文章、商品、聊天记录、文件接口 URL只用名词不用动词错误/addUser/deleteUser/updateUser正确/users/orders/goods2. 使用标准 HTTP 请求方法最核心动作表格请求方式作用对应操作GET查询资源查数据只读POST新建资源新增、提交PUT全量更新资源修改整条数据PATCH局部更新只改部分字段DELETE删除资源删除数据3. URL 层级清晰用路径区分集合资源/users所有用户单个资源/users/1001id1001 的用户子资源/users/1001/orders该用户的所有订单4. 用HTTP 状态码返回结果不用自定义数字统一标准状态码表格状态码含义200请求成功201创建成功POST204删除成功无返回内容400参数错误401未登录 / 无密钥403权限不足404资源不存在500服务器错误5. 统一返回数据格式固定 JSON 结构前后端统一json{ code: 200, msg: 请求成功, data: {} }6. 无状态最重要服务器不保存客户端任何状态服务器为所有的客户提供统一服务不关心客户端上下文每次请求必须自带身份凭证Token / API Key-每一次请求都是一个独立请求OpenAI API、国内大模型全部遵循每次请求带Authorization密钥三、实战接口对照表最常用以用户为例表格功能请求方式接口地址查询所有用户GET/users查询单个用户GET/users/{id}新增用户POST/users全量修改用户PUT/users/{id}局部修改用户PATCH/users/{id}删除用户DELETE/users/{id}四、请求参数规范GET 请求参数放URL 查询参数plaintextGET /users?name张三page1size10POST/PUT/PATCH参数放Body JSONjson{ username:test, age:20 }路径参数唯一标识放路由/users/1001五、RESTful 认证方式API 通用1. 最主流Bearer TokenOpenAI 全部用这个请求头携带密钥httpAuthorization: Bearer sk-xxxxxxxxxxx Content-Type: application/json2. 简单接口Query 参数plaintext/api/chat?keyxxx3. 传统Cookie/Session前后端网页用六、和 OpenAI API 关系重点OpenAI 接口 标准 RESTful API对话接口地址POST /v1/chat/completions请求方式POST创建对话会话资源鉴权Header Bearer APIKey传参JSON Body返回标准 JSON 结构国内千问、DeepSeek、星火全部复刻这套 RESTful 规范所以一套代码通调所有大模型七、RESTful 优点风格统一任何人一看就懂跨语言、跨平台通用适合前后端分离、微服务天然适配云服务、第三方 API无状态易做集群、负载均衡八、常见错误写法接口带动词 ❌/addUser用 GET 做新增 / 删除 ❌不使用标准状态码全返回 200会话依赖服务端存储状态参数杂乱不区分路径 / 查询 /body九、极简总结RESTful 用 HTTP 五个方法 名词 URL 标准状态码 JSON 格式 无状态鉴权统一管理网络资源的接口设计规则。现在所有 AI 大模型 API、后端接口、小程序接口全部基于它开发。