1.0 前言

代码写的好是很重要的，平常工作中路由规范设计也是非常重要的，这节就讲这个点。

2.0 路由 设计

  1.  project
  2. └── app
  3.     ├── routers # 路由层 控制路由
  4.         │   └── index.js
  5.         |———————page # 页面跳转
  6.         │                └── index.js
  7.         |———————api # ajax api 相关
  8.         │        └── v1.js

我们在路由设计可以把路由分为页面的跳转路由还有暴露给 Ajax 类的请求，那这里我们区分下这 2 种环境，放在 2 个目录下区分，page 目录下放跳转类，Api 放后者。这里我们以 Api 设计来说明。

  1. const Koa = require('koa')
  2. const  Router = require('koa-router')
  3. const  router = new Router()
  4. const BASE_API = 'v1'
  5. const { list, detail, add, update,remove } = require('../../controllers/user')
  6. router.get(`/api/${BASE_API}/user`, list) // 获取用户列表信息     
  7. router.post(`/api/${BASE_API}/user`, add) // 新增用户    
  8. router.put(`/api/${BASE_API}/user/:id`, update) // 根据 id 更新用户信息 
  9. router.get(`/api/${BASE_API}/user/:id`, detail) // 根据 id 查询用户信息
  10. router.delete(`/api/${BASE_API}/user/:id`, remove) // 根据 id 删除用户信息
  11. module.exports = router

2.0.1 版本

https://api.example.com/api/v1/xxx，我们要把 Api 的版本放在 url 里面，这样我们后面如果重构 某个接口，但又需要保持向下兼容，这样我们通过版本控制，就非常方便了。

2.0.2 http 动词

上面可以看到 查询用户列表和详情，我们用的是 get 请求，新增用户 用的 post， 更新用户用 update，删除用户 delete，这样我们通过这种标准，一眼就能看出来每个请求具体是干什么的，非常方便，常用的HTTP动词有下面五个：

  1. GET（SELECT）：从服务器取出资源（一项或多项）。
  2. POST（CREATE）：在服务器新建一个资源。
  3. PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
  4. PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
  5. DELETE（DELETE）：从服务器删除资源。

2.0.3 路径

路径又称”终点”（endpoint），表示 Api 的具体网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的”集合”（collection），所以 Api 中的名词也应该使用复数。
举例来说，有一个 Api 提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

  1. https://api.example.com/v1/zoos
  2. https://api.example.com/v1/animals
  3. https://api.example.com/v1/employees

2.0.4 状态码

服务器向用户返回的状态码可提示信息，通过这种 状态码能很好的知道发生什么事。常见的有以下一些：

  1. 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
  2. 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
  3. 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
  4. 204 NO CONTENT - [DELETE]：用户删除数据成功。
  5. 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
  6. 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
  7. 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
  8. 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
  9. 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
  10. 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
  11. 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
  12. 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

2.0.5 驼峰命名

使用小驼峰命名法作为属性标识符。

  1. { imgUrl: "http://xxx.com" }

不要使用下划线 img_url 或大驼峰命名法 ImgUrl。客户端会将 JSON 响应转换为 JavaScript 对象（通过调用JSON.parse(response)），然后调用其属性。因此，最好遵循 JavaScript 代码通用规范。
对比：

  1. person.img_url // 不推荐，违反JavaScript代码通用规范
  2. person.ImgUrl // 不推荐，JavaScript构造方法命名
  3. person.imgUrl // 推荐

以上就是常见的 Api 设计时候需要注意的一些地方，因为 page 的跳转都是 get 请求，比较简单，这里就不在讲 page 的跳转，参照 Api 就好。

3.0 小结

这节我们学习了 Api 定义的时候一些常见的基本原则。在实际工作的都是用的非常多的，大家可以好好梳理下。