API error return specification
It is forbidden to return API business errors by throwing exceptions
The API prohibits throwing Checked exceptions, that is, parameter errors, logic errors, and business errors in business processing are not allowed to be returned by throwing exceptions. Response#code, message is used to express business errors.
Note: Don't force the caller to write try{}catch() everywhere.
- Normal example:
1 |
Response<T> saveDesposit(...); |
- Counterexample:
1 |
T saveDesposit(...) throws ServiceException, IllegalArgumentException, ValidationException; |
It is forbidden to return API business errors by throwing exceptions
The API prohibits throwing Checked exceptions, that is, parameter errors, logic errors, and business errors in business processing are not allowed to be returned by throwing exceptions. Response#code, message is used to express business errors.
Note: Don't force the caller to write try{}catch() everywhere.
- Normal example:
1 |
Response<T> saveDesposit(...); |
- Counterexample:
1 |
T saveDesposit(...) throws ServiceException, IllegalArgumentException, ValidationException; |
If the caller needs to do error subdivision processing, the API provider must also provide a judgment tool class
- Normal example:
1 2 3 4 5 6 7 8 9 10 11 |
public void saveXXX(){
Response<T> result = xxxWriteService(...)
if (!result.isSuccess()){
if (xxxUtils.isBankUnSupport(result.getCode)){ <<<The API provider provides a tool class to parse the meaning of the code, and the meaning of the code can be continuously updated iteratively without the caller's perception.
//The bank channel is not opened, special reminder is required
...
}else{
...
}
}
} |
- Counterexample:
1 2 3 4 5 6 7 8 9 10 11 |
public void saveXXX(){
Response<T> result = xxxWriteService(...)
if (!result.isSuccess()){
if ("10101".equals(result.getCode)){ <<<The caller makes hard coding according to the error code value of the API provider, and the code is coupled.
//The bank channel is not opened, special reminder is required
...
}else{
...
}
}
} |
[Recommendation] API returns Chinese prompt information that can be directly displayed to the user
When the API fails, only the API implementer knows the reason and how to prompt it. Then, please provide the corresponding prompt information.
There are some error messages in the internationalization style in our system, but is the current internationalization implementation really as easy to use as you think?
Error message internationalization principle:
- Prompt information in the code internationalization configuration file
- Principles of Internationalization Tips
1) The internationalization of the prompt information occurs in the web layer. When the web layer starts, the resources/messages prompt information file of the web layer will be loaded.
2) When the REST API needs to return prompt information, the Web will decide which language to return the prompt information according to the Locale value in the HTTP request (for example: zh_CN, zh_TW, en_US, es_ES_Traditional_WIN, etc.). Return errorMessage in this language to the browser for prompting.
question:
1) In a distributed system, each application is autonomous by domain, and its resources/messages only maintain the errorMessage required by its own business.
2) When C Service returns errorMessage = template.status.not.match to XX Service in the figure, and XX Service directly transmits it to XX Web, the resources/messages of XX Web does not include template.status.not.match , so this errorMessage will not be able to correctly display the information it should prompt.
Therefore, the recommendation API returns Chinese prompt information that can be directly displayed to the user.
- Normal example:
1 2 3 4 5 6 7 8 9 10 11 12 |
public Response<Boolean> saveTemplate(...) {
try{
...
}catch(StateMachineException e){
log.warn("...");
...
return Response.fail("The template configuration is under review, please update it after the review is complete");
}catch(Exception e){
...
}
} |
- Counterexample:
1 2 3 4 5 6 7 8 9 10 11 12 |
public Response<Boolean> saveTemplate(...) {
try{
...
}catch(StateMachineException e){
log.warn("...");
...
return Response.fail("Template management state machine exception");
}catch(Exception e){
...
}
} |
[Recommended] Return a readable and instructive error message
- Normal example:
1 2 3 4 5 6 7 8 9 10 11 12 |
public Response<Boolean> saveTemplate(...) {
try{
...
}catch(StateMachineException e){
log.warn("...");
...
return Response.fail("The template configuration is under review, please update it after the review is complete");
}catch(Exception e){
...
}
} |
- Counterexample:
Example 1
1 2 3 4 5 6 7 8 9 10 11 12 |
public Response<Boolean> saveTemplate(...) {
try{
...
}catch(StateMachineException e){
log.warn("...");
...
return Response.fail("Template management state machine exception"); <<<< As a user, are you surprised?
}catch(Exception e){
...
}
} |
Example 2
1 2 3 4 5 6 7 8 9 10 11 12 |
public Response<Boolean> saveTemplate(...) {
try{
...
}catch(StateMachineException e){
log.warn("...");
...
return Response.fail(e.getMessage()); <<<< message no one can understand, it has no meaning
}catch(Exception e){
...
}
} |