Beego RESTful 小记
什么是 RESTful
这个的话在这里还是不做太多赘述，留等以后再开一篇关于 RESTful 的博客。这里只简单的说明。
RESTful 可以理解为一套接口规范，以资源为核心的一套规范。比如"用户信息"就可以看成是一个资源，针对"用户信息"这个资源就有相应的CURD操作。对应HTTP的Post，Put，Get，Delete请求。
HTTP 请求方法与CURD的对应关系
POST : 新增
PUT : 修改
PATCH : 部分修改
GET : 查询
DELETE : 删除
RESTful URL定义
例如有一个简单的用户表 t_user 对应程序中的结构体 User ,具体定义如下:
type User struct {
Id int64 `orm:"auto"`
Uid string `orm:cloumn(uid);size(128)`
Name string `orm:"column(name);size(32);unique"`
Psw string `orm:"column(psw);size(128);index"`
}
对应 User 设计符合 RESTful 规范的接口
查询所有用户
request
GET /api/v1/user/list
查询某个用户
GET /api/v1/user/get/:id
匹配 : /api/v1/user/get/1
新增用户
POST /api/v1/user/creation
修改用户
PUT /api/v1/user/modify
or
PATCH /api/v1/user/modify
删除用户
DELETE /api/v1/user/delete/:id
匹配 : /api/v1/user/1
这里与 REST ful 的规则还是有不一样的地方， Roy Fielding 的论文中的规则定义为使用同一个 URL 只根据 HTTP 请求方式的不同加以区分，但是这样的话在实际的操作发现，路由 match 时会有错误匹配的问题。例如：
GET /api/v1/user/:params
GET /api/v1/user/list
此时如果 list 的路由规则在 params 后面则 list 请求会被误判匹配到 params 的请求。
添加Beego路由
ns := beego.NewNamespace("api",
beego.NSNamespace("v1",
beego.NSNamespace("/user",
beego.NSRouter("/list", controller.UserController{}, "get:GetUser"),
beego.NSRouter("/modify", controller.UserController{}, "put:ModifyUser"),
beego.NSRouter("/creation", controller.UserController{}, "post:CreateUser"),
beego.NSRouter("delete/:id", controller.UserController{}, "delete:DeleteUser"),
beego.NSRouter("/get/:id", controller.UserController{}, "get:GetUserById"),
),
),
)
beego.AddNamespace(ns)
Response 状态码
以下内容主要参考阮一峰的博客感觉说的很清楚。特此借鉴一下
1xx : 相关信息
2xx : 操作成功
3xx : 重定向
4xx : 客户端错误
5xx : 服务端错误
1xx 状态码
API 一般不会用到 1xx 状态码
2xx 状态码
200 状态码表示操作成功,但是不同的方法可以返回更精确的状态码
- GET : 200 OK
- POST : 201 Created
- PUT : 200 OK
- PATCH : 200 OK
- DELETE : 204 No Content
上述中， POST 返回 201 状态码，表示新资源创建成功， DELETE 返回 204 状态码，表示资源已经不存在
此外还有 202 Accepted 状态码表示服务器已经收到请求，但未进行处理，通常用于异步操作。
HTTP/1.1 202 Accepted
{
"user": {
"href": "/api/v1/user/register",
"time": "1391141532000"
}
}
以上是注册用户时进行手机号校验返回当前服务器的时间，作为验证码有效性计时的计算。同时给定新的请求 URL 以完成注册。
3xx 状态码
API 一般用不到 301（永久重定向）、302（暂时重定向，307也是这个含义），因为它们可以由应用级别返回，浏览器会直接跳转，API级别可以不考虑这两种情况。
API用到的3xx状态码，主要是 303 ，表示参考另一个URL。它与 302 和 307 的含义一样，也是“暂时重定向”，区别在于 302 和 307 用于 GET 请求，而 303 用于 POST、PUT 和 DELETE 请求。收到 303 之后，浏览器不会自动跳转，而是让用户选择下一步怎么办。
HTTP/1.1 303 See Other
Location: /api/orders/12345
4xx 状态码
4xx 状态码表示客户端错误，主要有以下几种：
- 400 Bad Request ： 服务器不理解客户端请求，未做任何处理。
- 401 Unauthorized ： 用户未提供身份验证凭据，或者没有通过身份验证。
- 403 Forbidden ： 用户通过身份验证，但是不具有访问资源所需的权限。
- 404 Not Found ： 所请求的资源不存在，或不可用
- 405 Method Not Allowed ： 用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限范围内
- 410 Gone ： 所请求的资源已从这个地址转移，不再可用
- 415 Unsupported Media Type ： 客户端要求返回格式不支持。比如 API 只支持 JSON 格式的返回，而客户端要求返回 XML 格式。
- 422 Unprocessable Entity ： 客户端上传的附件无法处理，导致请求失败。
- 429 Too Many Requests ： 客户端请求次数超过限额
5xx 状态码
5xx 状态码表示服务端错误。一般来说，API不会透露服务器的详细信息，所以只要两个状态码就够了。
- 500 Internal Server Error ： 客户端请求有效，服务器处理时发生了意外。
- 503 Service Unavailable ： 服务器无法处理请求，一般用于网站维护状态。
请求与响应格式
服务端回应的 HTTP 头的 Content-Type 属性设为 application/json。
客户端请求是，也要明确告诉服务端，可以接受 JSON 格式，即请求头中 ACCEPT 属性也要设成 application/json。
错误响应
发生错误时不应该返回 200 状态码，正确的做法是，状态码反映返回发生的错误，具体错误信息放在数据体里面返回。