Microservice interface verification

Sanfeng soft Zhang Sanfeng

API design plan

Http requests are divided into URL convention rules and request parameter rules URL rules: http://{server}/{product}/{version}/{logic}/{method}?{query_string }　

1.server: is the specific service domain name
2.product: is the application project name
3.version: is the specific version number, which is convenient for future function expansion, can be tentatively set as v1, v2
4.logic: is the preliminary division of specific business logic For example, the back-end management method, the request method on the app side 5. method
: The specific
request parameters of the specific business method are determined by the specified method method, and all are used as the HTTP GET/POST parameter list.

Http response rules

The HTTP response code is 200, and the return result is in the form of a JSON string: If the response result is correct, the return result is as follows:


{　　
　　　　　　data : { // 请求数据，对象或数组均可
　　　　　　　　user_id: 123,
　　　　　　　　user_name: "zwz",
　　　　　　　　user_avatar_url: "http://www.abc.com/1.jpg"
　　　　　　　　...
　　　　　　},
　　　　　　msg : "done", // 请求状态描述，调试用
　　　　　　success : 1,
　　　　　　code" : 1001, // 业务自定义状态码
　　　　　　extra : { // 其他扩展的数据，字段、内容不定
　　　　　　　　type: 1,
　　　　　　　　desc: "签到成功！"
　　　　　　}
　　　　}

If the response result fails, the following result is returned:


{
　　　　　　data : { // 请求数据，对象或数组均可
　　　　　　},
　　　　　　msg : "Internal Server Error", // 请求状态描述，调试用
　　　　　　success : 0,
　　　　　　code : 5001, // 业务自定义状态码
　　　　　　extra : {
　　　　　　}
　　　　}
}

error code

When designing the API, it is best not to bind business error codes with HTTP status codes, and redefine a set of business error codes to distinguish HTTP status codes. It is also best to have a set of specifications for the definition of status codes, similar to HTTP status codes, which can be simply classified according to user-related, authorization-related, and various services.


// Code 业务自定义状态码定义示例
　　　　// 授权相关
　　　　1001: 无权限访问
　　　　1002: access_token过期
　　　　1003: unique_token无效
　　　　...

　　　　// 用户相关
　　　　2001: 未登录
　　　　2002: 用户信息错误
　　　　2003: 用户不存在

　　　　// 业务相关
　　　　3001: 业务XXX
　　　　3002: 业务XXX

　　　　// 系统异常
　　　　5001：Internal Server Error

Spring request parameter verification

The data verification supported by SpringMVC is the JSR303 standard, which is verified by marking @NotNull, @Max, etc. on the bean properties. JSR303 provides many annotation interfaces, and SpringMVC uses hibernate for these verifications, so we need to add a validator package of hibernate: the framework has provided verification as follows:


@Null 被注释的元素必须为 null
@NotNull 被注释的元素必须不为 null,不能为 null , 可以为 ""
@AssertTrue 被注释的元素必须为 true
@AssertFalse 被注释的元素必须为 false
@Min(value) 被注释的元素必须是一个数字，其值必须大于等于指定的最小值
@Max(value) 被注释的元素必须是一个数字，其值必须小于等于指定的最大值
@DecimalMin(value) 被注释的元素必须是一个数字，其值必须大于等于指定的最小值
@DecimalMax(value) 被注释的元素必须是一个数字，其值必须小于等于指定的最大值
@Size(max=, min=) 验证对象（Array,Collection,Map,String）长度是否在给定的范围之内
@Digits (integer, fraction) 被注释的元素必须是一个数字，其值必须在可接受的范围内
@Past 被注释的元素必须是一个过去的日期
@Future 被注释的元素必须是一个将来的日期
@Pattern(regex=,flag=) 被注释的元素必须符合指定的正则表达式

Hibernate Validator提供的校验注解：
@NotBlank(message =) 只能作用在String上，不能为null，而且调用trim()后，长度必须大于0
@Email 被注释的元素必须是电子邮箱地址
@Length(min=,max=) 被注释的字符串的大小必须在指定的范围内
@NotEmpty 被注释的字符串的必须非空，不能为 null、"",可以为 " "
@Range(min=,max=,message=) 被注释的元素必须在合适的范围内

to sum up

Of course, relying solely on the verification provided by the framework cannot meet real-time changing business, so you need to write some custom verification rules based on the business. Of course, this is relatively simple.