How to design API return code (error code)?

Click on the official account ,Java dried food Timely delivery

source ：https://ken.io/note/api-errorcode-or-resultcode-desgin

One 、 Preface

Client request API, Usually we need to judge by the return code API Whether the returned results meet the expectations , And how to deal with the returned content

I believe many students have suffered from the confusion of return code definition , yes , we have API The return code is int type , There are plenty of them string type , Some use 0 It means success , Another use 1 It means success , It's also useful ”true” It means success , Come across such a thing , It can only be said ： Have a headache

API The design of return code should be taken seriously , After all, good return code design can reduce communication costs and program maintenance costs .

Two 、HTTP Status code reference

With HTTP Take the status code as an example , In order to more clearly express and distinguish the meaning of status code ,HTTP The state is segmented .

piecewise	Segment description
1XX	Information , The server receives the request , Requester is required to continue
2XX	success , Operation received and processed successfully
3XX	Redirect , Further action is required to complete the request
4XX	Client error , The request contains a syntax error or could not be completed
5XX	Server error , The server encountered an error while processing the request

For back-end development , What we usually see is ：

2XX Status code , such as 200-> The request is successful ,

5XX Status code , such as 502-> Server exception , Usually, the service is not running properly , Or code execution error

The cause of the problem can be preliminarily determined through the status code ,HTTP The design idea of state is worth learning .

3、 ... and 、 Parameter conventions

Although it is a return code design , But only code You can't , There should also be corresponding message, So that people can understand

Field	type	explain
code	int	Return code
message	string	Return code description

Reference resources HTTP The idea of status code , We segment the error code

Return code value	explain
0	success
99999	An unknown exception occurred in the system
10000-19999	Parameter check error
20000-29999	A Step execution failed
30000-39999	B Step execution failed

Through this design , It is very convenient to distinguish between programs and people API Return result of , The key is unity ！ Want to be an architect , This The architect's Atlas suggests taking a look , Little detours .

Four 、 Individualization Message

Usually ours message It's all for Engineers , But in different scenarios , The same mistake , Users may need to see different error prompts . Click on the official account ,Java dried food Timely delivery

For example 20000-29999 Indicates that the order creation failed ：

• 20001, Order creation failed , There are orders in progress

• 20002, Order creation failed , The previous order is being queued for creation

If these two error conditions are shown to users , Maybe it's just for seeing ： I'm sorry , You have an order in progress , Please go to my order list to process .

But for API Come on , The returned information must be accurate , But what users see must be translated , The caller of this translation can do , But usually API Providers to provide personalized Message Ability will be better .

We can configure the translated messages to the database , And cache to Redis perhaps API This machine

application_id	code	message
100001	20001	I'm sorry , You have an order in progress , Please go to my order list to process .
100001	20002	I'm sorry , You have an order in progress , Please go to my order list to process .

Then when the request processing is finished and is about to return , according to application_id+code, To match and replace message.

request-api-get-my-message

So we can make the phone APP Users of 、 Users of wechat applet 、 Business users who place orders on the web page see different messages . The latest interview questions have been sorted out , You can Java Interview library applet online brush questions .

5、 ... and 、 Unified processing of return information

With a unified code, We can go through Nginx perhaps APM Tool Statistics API request Code Quantity and distribution information .

We can according to the unit time 99999 To do sth API Abnormal alarm of

We can use Code Return pie chart , Help us discover the system 、 Problems in business processes

wait , All in all , Good return code design , Can help us improve communication efficiency , Reduce the maintenance cost of the code .

Good start ！ Reissue 10,000 Red envelope cover

2021 What happened in 10 It's a technical event ！！

23 Design mode and Practice （ Very comprehensive ）

replace Log4j2！tinylog Born in the sky

Based on a Spring Boot The fairy's private life project

Explode ！Java Xie Cheng is coming ！

Weigh on Guan Xuan ：Redis Here comes the object mapping framework ！！

Recommend a code artifact , Save at least half the amount of code ！

Programmers are proficient in various technical systems ,45 It is difficult to find a job at the age of ！

Spring Boot 3.0 M1 Release , Formal abandonment Java 8

Spring Boot Learning notes , This is so complete ！

Focus on Java Technology stack, see more dry goods

obtain Spring Boot Practical notes ！