How to design API return codes (error codes)?

2022 The global C++ And system software technology conference | 3 month 11-12 Japan · Shanghai Click to learn more 》>>>

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 ！

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 .

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

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

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 .

Recent hot article recommends ：

1.1,000+ Avenue Java Arrangement of interview questions and answers (2022 The latest version )

2. Explode ！Java Xie Cheng is coming ...

3.Spring Boot 2.x course , It's too complete ！

4.20w Programmer red envelope cover , Get it quickly ...

5.《Java Development Manual （ Song Mountain version ）》 The latest release , Download it quickly ！

I think it's good , Don't forget to like it + Forward ！