Shulou(Shulou.com)06/03 Report--

This article mainly explains "how to write a good back-end API interface". The content in the article is simple and clear, and it is easy to learn and understand. Please follow the editor's train of thought to study and learn how to write a good back-end API interface.

Interface interaction

The front-end and the back-end interact. The front-end requests the URL path according to the agreement and passes in the relevant parameters. The back-end server receives the request, carries on the business processing, and returns the data to the front-end.

I will not introduce the restful style of URL path and the requirements of common request headers for passing parameters (such as app_version,api_version,device, etc.). Friends can understand it by themselves, which is relatively simple.

Let me focus on how the back-end server can return data to the front end.

Return format

When the backend returns to the frontend, we usually use the JSON style, which is defined as follows:

{# return status code code:integer, # return information description message:string, # return value data:object}

① CODE status code

Code returns the status code. Generally, friends can add whatever they need when developing.

If the API returns a user permission exception, let's add a status code of 101. Next time, if you want to add a data parameter exception, add a status code of 102. Although this can satisfy the business as usual, the status code is too messy.

We should be able to refer to the status code returned by the HTTP request. Here are the common HTTP status codes:

200-request successful 301-Resources (web pages, etc.) are permanently transferred to other URL 404-requested resources (web pages, etc.) do not have 500-internal server error

We can refer to such a design, and this benefit classifies the error type into a certain interval, and if the interval is not enough, it can be designed as four digits.

# 1000 '1999 interval indicates parameter error # 2000' 2999 interval indicates user error # 3000 '3999 indicates interface exception

In this way, after getting the return value, the front-end developer can know what is wrong according to the status code, and then quickly locate it according to the description of Message-related information.

② Message

This field is relatively easy to understand, that is, how to give a friendly prompt when an error occurs. General designs are designed together with Code status codes, such as:

Then define the status code in the enumeration:

The status code and information will correspond one by one, which is easier to maintain.

③ Data

Returns the data body in JSON format, and the JSON body varies according to different business.

We are going to design a return body class Result:

Control layer Controller

We will process the business request at the Controller layer and return it to the front end, taking the Order order as an example:

We see that after getting the Order object, we use the Result constructor to wrap the assignment and then return it.

Friends have not found that the construction method of such packaging is not very troublesome, we can optimize it.

Aesthetic optimization

We can add static methods to the Result class and understand at a glance:

Let's reinvent Controller:

The code is not more concise, but also beautiful.

Elegant optimization

Above we saw the addition of static methods to the Result class to make the business processing code concise.

But have you guys noticed that there are a few questions:

The return of each method is an Result encapsulated object with no business meaning.

In the business code, we call Result.success on success and Result.failure on exception error. Is it superfluous.

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

The best way is to return the real business object directly, and it is best not to change the previous business method, as shown below:

This and our usual code is the same, very intuitive, directly return the order object, this is not perfect. So what is the implementation plan?

Realization scheme

Friends, how to achieve is not a little bit of ideas, in the process, we need to do a few things:

Define an annotation @ ResponseResult to indicate that the value returned by this interface needs to be wrapped.

Intercept the request to determine whether the request needs to be annotated by @ ResponseResult.

The core step is to implement the interfaces ResponseBodyAdvice and @ ControllerAdvice, determine whether the return value needs to be wrapped, and if so, rewrite the return value of the Controller interface.

① annotation class

Used to mark the return value of the method, whether it needs to be wrapped:

② interceptor

To intercept a request, whether the value returned by this request needs to be wrapped is actually parsing the @ ResponseResult annotation at run time.

The core idea of this code is to get this request, whether it needs to return a value wrapper, and set an attribute tag.

③ rewrite return body

The above code is to determine whether the return value wrapper is needed, and wrap it directly if necessary. Here we only deal with the normal successful packaging, what if the method reports an exception?

Handling exceptions is also relatively simple, as long as you determine whether body is an exception class.

How to do the overall exception handling, space reasons, Lao Gu will not introduce here, as long as the train of thought is clear, self-transformation on the line.

④ rewrites Controller

Add @ ResponseResult annotation to the controller class or method body, so it's OK, so it's simple. To return to the completion of the design idea, is not both concise and elegant.

Thank you for reading. The above is the content of "how to write a good back-end API interface". After the study of this article, I believe you have a deeper understanding of how to write a good back-end API interface, and the specific usage needs to be verified in practice. Here is, the editor will push for you more related knowledge points of the article, welcome to follow!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.