http-response

HTTP

这篇文章尝试定义一种Http响应的规范,可能不通用,但我尝试与我合作的人达成在Http响应上的共识。

这篇规范由三个部分组成,正常、异常、分页,不同的状态有不同的响应格式和Http状态码。

如果你认为这些方法合理,可以作为自己团队的标准,如果有更好的方案,也欢迎Fork。

Java的完整实现请访问Github

一般响应

在常见的场景,当对一个Restful的资源请求时,我们期望得到一个结果。可能是XML,也可能是JSON。我见过非常多不同的格式,
比如在结果中用data字段包含数据,或者data字段也叫做result字段。而这篇规范设计希望直接返回期望的结构。

下面是一个省略了的HTTP请求和响应。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
POST /user
Content-Type: application/json

{
"username": "CJ",
"email": "weicongju@gmail.com"
}

HTTP/1.1 200

{
"username": "CJ",
"email": "weicongju@gmail.com"
}

包装过的响应。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /user
Content-Type: application/json

{
"username": "CJ",
"email": "weicongju@gmail.com"
}

HTTP/1.1 200

{
"data": {
"username": "CJ",
"email": "weicongju@gmail.com"
},
"status": 0,
"messaage": "success"
}

异常

业务出现异常时,用code和message接触业务的异常。这里异常分为两种,业务异常和系统异常。

1
2
3
4
5
HTTP/1.1 400 Bad Request
{
"code": "ip_illegality",
"message": "你的IP已经被封禁"
}

成功

1
2
3
4
5
{
"username": "cj",
"password": "hash code",
"email": "weicongju@gmail.com"
}

表单校验

1
2
3
4
5
6
@RestController
class UserController {
public User register(@Valid RegistrationCommand) {
return null;
}
}
1
2
3
4
5
class RegistrationCommand {

@NotNull
private String username;
}

表单校验失败后,http状态码为400 bad request。响应体是一个对象,包含code field message,code用一个英文单词或者短语表达,field是失败的字段名,message是原因。

1
2
3
4
5
6
7
8
9
10
HTTP/1.1 400 Bad Request
Content-Type: application/json

[
{
"code": "NotNull",
"field": "username",
"message": "username 不能是 null"
}
]

Java

在异常类上使用注解@BusinessException,过滤器检查到该注解后响应异常。过滤器自动把驼峰命名转换成Snake Case作为code。

1
2
3
@BusinessException
class IpIllegalityException extends Exception {
}

@BusinessException("ip")将会把code修改成ip

1
2
3
4
5
HTTP/1.1 400 Bad Request
{
"code": "ip_banned",
"message": "你的IP已经被封禁"
}

前端

1
2
3
4
5
6
7
8
try {
axios.post("/user", {"username": "cj", "password", "123456", "email": "i@imcj.me"})
} catch (e) {
console.debug(e.code)
console.debug(e.message)

this.setData({"message": e.mssage})
}