Browser URL规范

基本规范

  1. 不允许出现没有意义的下 URL
  2. 只能允许英文字母（az，全小写）、数字（09），英文连接符(-)
  3. https://展开的层级目录内容中不允许出现“丨”、下划线“_”、多斜杠字符“//”、“+”、“#”（除特殊情况比如开发人员使用#锚点定位）
  4. 层次命名不要超过3个单词
    正确示例：https://www.example.com/first/second/third.html
    错误示例：https://www.example.com/first/second/third/forth.html
  5. 总 URL 长度不要超过 72 个字符
  6. 不允许存在多余参数或空格
  7. URL 目录命名需要避免歧义，通常使用英文全称，英文无法满足时使用直译
  8. URL 中参数尽可能少，不要超过 3 个，一般 2~3 即可
  9. URL应该呈现一个降级的次序（例如：域名/类型/分类/标题）
  10. 如果是内容资源URL，不允许以参数的方法显示
    例如：http://www.uxuexi.cn/user.html?userId=123 需要改成 http://www.uxuexi.cn/user/123.html

类型设置

  1. 目录：频道页或栏目，最后面必须加上/。获得更多搜索权重
    http://www.uxuexi.cn/search/
  2. 网页：表现网页内容，必须以.html结尾
    http://www.uxuexi.cn/user/123.html
  3. 特定功能或交互：统一以.json或.html结尾
    http://www.uxuexi.cn/addcomment.json

静态化

  1. 不经常更新的内容采用静态化
    http://course.uxuexi.cn/detail/111.html URL中不允许使用 ? 带参数
  2. 实时更新的内容采用伪静态
    http://www.uxuexi.cn/user/111.html URL中不允许使用 ? 带参数

RESTful

URI 规范

  1. /不应该出现在 URL 末尾
  2. RESTful API 对 URI 资源的定义具有唯一性，一个资源对应唯一的一个地址
    如果访问到末尾含/的地址，服务端应该 301 到没有/的地址
  3. 路径中使用中横线-代替下划线进行单词分割
  4. 参数名称使用下划线_进行连接
  5. 路径中统一使用小写字母
  6. 参数列表进行 encode

API 演进

版本。常见三种方式：

  1. 在 uri 中放版本信息：GET /v1/users/1 // 使用的最多
  2. Accept Header：Accept: application/json+v1
  3. 自定义 Header：X-Api-Version: 1

资源集合 vs 单个资源

资源集合：

/zoos //所有动物园
/zoos/1/animals //id为1的动物园中的所有动物

单个资源：

/zoos/1 //id为1的动物园
/zoos/1;2;3 //id为1，2，3的动物园

避免层级过深的URI

/在 url 中用于表达层级，用于按实体关联关系进行对象导航，一般根据 id 导航

GET /animals?zoo=1&area=3

对Composite资源的访问

服务器端的组合实体必须在uri中通过父实体的id导航访问

组合体不是 first-class 的实体，其生命周期完全依赖父实体，无法独立存在，实现上通常是对数据库某些表的抽象

// User 
// Address 对 User 某些字段的抽象
GET /user/1/addresses

Request

GET 查询

GET /zoos
GET /zoos/1
GET /zoos/1/employees

POST 创建单个资源

POST /animals  //新增动物
POST /zoos/1/employees //为id为1的动物园雇佣员工

PUT 全量更新单个资源

PATCH 部分更新单个资源

PUT /animals/1
PUT /zoos/1

DELETE 删除

DELETE /zoos/1/employees/2
DELETE /zoos/1/employees/2;4;5
DELETE /zoos/1/animals  //删除id为1的动物园内的所有动物

复杂查询

.

示例

备注

过滤条件

?type=1&age=16

允许一定的uri冗余，如/zoos/1与/zoos?id=1

排序

?sort=age,desc

投影

?whitelist=id,name,email

分页

?limit=10&offset=3

Format

Content-Type: application/json

POST /v1/animal HTTP/1.1
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24
 
{   
  "name": "Gir",
  "animalType": "12"
}

Content-Type: application/x-www-form-urlencoded
（POST 表单）

POST /login HTTP/1.1
Host: example.com
Content-Length: 31
Accept: text/html
Content-Type: application/x-www-form-urlencoded
 
username=root&password=Zion0101

Content-Type: multipart/form-data

（表单存在文件上传）

Response

  1. 不要包装：response 的 body 直接就是数据，不要做多余的包装
  2. 各HTTP方法成功处理后的数据格式：

·

response 格式

GET

单个对象、集合

POST

新增成功的对象

PUT/PATCH

更新成功的对象

DELETE

空

  1. json格式的约定：
  1. 时间用长整形(毫秒数)，客户端自己按需解析
  2. 不传null字段
  1. 分页 fixme
{
    "page":{"limit":10,"offset":0,"total":729},
    "data":[{},{},{}...]
}

错误处理

  1. 不要发生了错误但给 2xx 响应，客户端可能会缓存成功的http请求；
  2. 正确设置http状态码，不要自定义；
  3. Response body 提供 1) 错误的代码（日志/问题追查）；2) 错误的描述文本（展示给用户）

服务器端抛出异常一般分为两类：

  • 业务异常：参数校验不通过等，由业务代码抛出
  • 非业务异常：不在预期内的异常，一般由框架抛出

业务异常必须提供两种信息：

  1. HTTP 响应码
  2. 异常的文本描述

在 Controller/API 层使用统一的异常拦截器（中间件）：

  1. 设置 HTTP 响应状态码：
  1. 业务类异常，用它指定的 HTTP code；
  2. 非业务类异常，统一500；
  1. Response Body 的错误码：异常类名
  2. Response Body 的错误描述：
  1. 业务类异常，用它指定的错误文本；
  2. 非业务类异常，线上可以统一文案如“服务器端错误，请稍后再试”，开发或测试环境中用异常的 stacktrace，服务器端提供该行为的开关

常用的http状态码及使用场景：

code

scenario

400

bad request，常用在参数校验

401

unauthorized，未经验证的用户，常见于未登录。如果经过验证后依然没权限，应该 403（即 authentication 和 authorization 的区别）

403

forbidden，无权限

404

not found，资源不存在

500

internal server error，非业务类异常

503

service unavaliable，由容器/框架抛出，自己的代码不要抛这个异常

服务性资源

无法使用 URI 映射时

可以把这些服务看成资源，计算的结果是资源的 presentation ，按服务属性选择合适的 HTTP 方法

GET /search?q=filter?category=file  搜索
GET /distance-calc?lats=47.480&lngs=-122.389&late=37.108&lnge=-122.448

POST /batch-publish-msg
[{"from":0,"to":1,"text":"abc"},{},{}...]

异步任务

对耗时的异步任务，服务器端接受客户端传递的参数后，应返回创建成功的任务资源，其中包含了任务的执行状态。客户端可以轮训该任务获得最新的执行进度

提交任务：
POST /batch-publish-msg
[{"from":0,"to":1,"text":"abc"},{},{}...]
 
返回：
{"taskId":3,"createBy":"Anonymous","status":"running"}

客户端轮询：
GET /task/3
{"taskId":3,"createBy":"Anonymous","status":"success"}

如果任务的执行状态包括较多信息，可以把“执行状态”抽象成组合资源，客户端查询该状态资源了解任务的执行情况

提交任务：
POST /batch-publish-msg
[{"from":0,"to":1,"text":"abc"},{},{}...]
 
返回：
{"taskId":3,"createBy":"Anonymous"}

客户端轮询：
GET /task/3/status
{"progress":"50%","total":18,"success":8,"fail":1}   // 结果抽象