计网协议杂记
URL
URL(Uniform Resource Locators)是统一资源定位器的简称，Web浏览器通过URL从Web服务器请求页面。其一般格式为：
1 | |
除了 URL，还有 URI 的概念，URI (Uniform Resource Identifier) 是统一资源标识符的简称，用于唯一标识一个资源，但 URL 不仅标识一个资源，还指明了如何定位到这个资源。
参考文献
MIME简述
媒体类型（也通常称为多用途互联网邮件扩展或 MIME 类型）是一种标准，用来表示文档、文件或一组数据的性质和格式。浏览器通常通过MIME类型而非文件扩展名来决定如何处理URL。
其格式为：type/subtype ，即一个类型和一个子类型。类型分为独立类型和多部粉类型，多部份类型可分成不同部分的独立文件。
RestFul API
RestFul API 也叫 REST API，REST 是 REpresentational State Transfer 的缩写，或者简单点，是 Resource Representational State Transfer 的缩写
- Resource 一个资源可以是一个集合，也可以是单个个体，每一种资源都有特定的 URI 与之对应
- Representational 资源是一种信息实体，其具体呈现出来的形式，如
json、xml、image、txt等等称为其“表现形式” - State Transfer 通过 REST 中的状态转移（如 crud）来描述服务器资源端的状态和相关操作
HTTP 方法
REST API 定义了一组请求方法，以表明要对给定资源执行的操作。指示针对给定资源要执行的期望动作。
| 方法名 | 说明 |
|---|---|
GET |
获取特定资源，常用于向服务器查询信息 |
POST |
传输实体文本，在服务器上创建一个新的资源 |
HEAD |
获得报文首部。获取和GET请求相同的响应，但没有响应体 |
PUT |
传输文件，更新服务器上的资源 |
DELETE |
删除资源 |
OPTION |
询问支持的方法 |
TRACE |
追踪路径 |
CONNECT |
使用隧道协议进行TCP通信 |
PATCH |
更新服务器上的资源 |
状态码
| 2xx 成功 | 3xx 重定向 | 4xx 客户端错误 | 5xx 服务器错误 |
|---|---|---|---|
| 200 OK | 301 永久移动到新 URL | 400 不良请求 | 500 服务器错误 |
| 201 已创建资源 | 302 找到 | 401 未授权 | 502 网关错误 |
| 202 已接受，但未完成创建资源 | 303 见其他，发送对资源的引用但不强制客户端下载状态 | 403 禁止访问 | 504 网关超时 |
| 204 无内容 | 304 资源未修改，与 204 类似 | 404 未找到 | |
| 307 临时重定向，不会处理客户端的请求 | 405 方法不允许 | ||
| 406 响应不可接受 | |||
| 412 前提条件失败，这里的前提条件通常是客户端要求的 | |||
| 415 不支持的媒体类型 |
命名规范
- 网址和接口中不能有动词，只能有名词，API 中的名词也应该用复数
- 不用大写字母，建议用
-而不是_ - 善用版本化 API
怎么理解呢? 就比如 OpenAI 的对话生成接口为/v1/chat/completions, 其中的/v1就是版本号
规约
【强制】 前后端数据列表相关的接口返回，如果为空，则返回空数组
[]或空集合{}。【强制】 服务端发生错误时，返回给前端的相应信息必须包含 HTTP 状态码、errorCode、errorMessage、用户提示信息四个部分。这四个部分的设计对象分别是浏览器、前端开发、错误排查人员、用户。
【强制】 对于需要使用超大整数的场景，服务端一律使用 String 返回，禁止使用 Long 类型。
Java服务端如果直接返回Long整型数据给前端，Javascript会自动转换为Number类型。Long类型能表示的最大值是 $2^{63}-1$，在取值范围之内，超过 $2^{53}$（9007199254740992）的数值转化为 Javascript 的Number 时，有些数值会产生精度损失。扩展说明，在Long取值范围内，任何2的指数次的整数都是绝对不会存在精度损失的，所以说精度损失是一个概率问题。若浮点数尾数位与指数位空间不限，则可以精确表示任何整数，但很不幸，双精度浮点数的尾数位只有52位。
通常在订单号或交易号大于等于16位，大概率会出现前后端订单数据不一致的情况。
【强制】 HTTP 请求通过 URL 传递参数时，不能超过2048字节。HTTP 请求通过 body 传递内容时，必须控制长度（nginx 默认限制为 1MB，tomcat 默认限制是 2MB）。
【强制】 分页场景中，若用户输入的参数小于1，则前端返回第一页参数给后端；后端发现用户输入的参数大于总页数，则直接返回最后一页。
【推荐】 前后端时间格式统一为
yyyy-MM-dd HH:mm:ss，统一为 GMT。