API interface, unified format return! Have you learned anything?

This article comes from the public number: Java Travel

preface

In the mobile Internet, distributed, micro-service prevailing today, now the vast majority of projects are using the micro-service framework, front-end separation, (off-topic: front-end job responsibilities are more and more clear, now the front end is called the big front end, technology stack and ecosystem has been very mature;

The general overall architecture of the general system is shown below:

It should be noted that some small partners will reply that this architecture is too simple, too low, what gateway ah, cache ah, message middleware ah, no. Because the main introduction of this article is API interface, so we focus on, the other module partners to add their own.

Interface interaction

The front end interacts with the back end, the front end requests the URL path according to the convention, and passes in the relevant parameters, and the back-end server receives the request, processes the business, and returns the data to the front end.

The restful style of the URL path, as well as the requirements of the public request header for incoming parameters (e.g. app_version, api_version, device, etc.), are not introduced here, and the small partners can understand it themselves, which is relatively simple.

How does the back-end server implement the return of data to the front end?

Return to the format

The back end is returned to the front end we generally use the JSON body, as defined as follows:

{
  #返回状态码
  code:integer,
  #返回信息描述
  message:string,
  #返回值
  data:object
}

CODE status code

code returns the status code, and the average small partner adds whatever they need when they develop.

If the interface to return user rights exception, we add a status code for 101 bar, the next time to add a data parameter exception, add a 102 status code. This will satisfy the business as usual, but the status code is too messy

We should be able to refer to the status code returned by the HTTP request

：下面是常见的HTTP状态码：
200 - 请求成功
301 - 资源（网页等）被永久转移到其它URL
404 - 请求的资源（网页等）不存在
500 - 内部服务器错误

We can refer to a design that classifies the error type into a range and, if it is not enough, can be designed as four digits.

#1000～1999 区间表示参数错误
#2000～2999 区间表示用户错误
#3000～3999 区间表示接口异常

This way, the front-end developer can know, based on the status code, what the error is, and then according to the message-related information description, can quickly locate.

Message

This field is relatively simple to understand, that is, when an error occurs, how to be friendly to prompt. A general design is designed with a code status code, for example

Then defined in the enumeration, the status code

Status code and information will correspond one by one, better maintenance.

Data

Returns the data body, the JSON format, depending on the business and the JSON body.

We're going to design a return body Result

Control layer Controller

We process business controller at the controller layer and return them to the front end, taking order orders as an example

We see that after we get the order object, we wrap the assignment using the Result construction method and then return it. Little partners have not found that the construction method of such packaging is not very troublesome, we can optimize it.

Beautiful and beautifying

In the Result class, we can add static methods and understand them at a glance

Let's remodel Controller

The code is not more concise, but also beautiful.

Elegant optimization

Above, we see the addition of static methods to the Result class to keep the business processing code simple. But did the little buddies find a few problems:

1. The return of each method is a Result encapsulation object with no business implications

2, in the business code, when successful, we call Result.success, abnormal error call Result.failure. Is not a lot more

3, the above code, to determine whether the id is null, in fact, we can use hibernate validate to do the verification, there is no need to make a judgment in the method body.

The best way for us to return directly to real business objects is not to change the way we did business before, as shown below

This is the same as our usual code, very intuitive, direct return order object, this is not perfect. So what's the implementation?

Implement the scenario

It's not a bit of an idea how the little guys get there, and there are a few things we need to do in the process

1, define an annotation @ResponseResult, indicating that the value returned by this interface needs to be wrapped

2, intercept the request, determine whether the request needs to be @ResponseResult annotated

3, the core step is to implement the interface ResponseBodyAdvice and @ControllerAdvice, to determine whether the package return value is required, if necessary, the Return value of the Controller interface is rewritten.

The annotation class

The return value used to mark the method and whether it needs to be wrapped

Interceptor

Intercept the request, whether the value returned by this request needs to be wrapped, in fact, is the time to run, parse @ResponseResult annotations

The core idea of this code is to get this request, whether you need to return a value wrapper, and set a property tag.

Override the return body

The code above is to determine whether a value wrapper needs to be returned and to wrap directly if needed. H ere we only deal with the normal successful packaging, if the method body report abnormal how to do? Handling exceptions is also simple, as long as you determine whether body is an exception class.

How to do the overall abnormal handling, length reasons, old gu here do not do the introduction, as long as the idea is clear, self-reform on the line.

Rewrite Controller

Add @ResponseResult annotations to the controller class or method body, so ok, it's easy. To this return to the design ideas completed, is not concise, and elegant.

There is no other room for optimization in this scheme, of course. S uch as: each request to reflect, the method to get the request needs to wrap, in fact, can do a cache, do not need to resolve every time. Of course, the overall idea of understanding, small partners can be on this basis to expand their own.

Above is W3Cschool编程狮 about the API interface, unified format return! Have you learned anything about the introduction, I hope to help you.