1. [Mandatory] The API for front-end and back-end interaction needs to specify the protocol, domain name, path, request method, request content, status code, and response
body.
Note:
1) Protocol: The production environment must use HTTPS.
2) Path: Each API needs to correspond to a path, indicating the specific request address of the API:
a) Represents a resource, which can only be a noun, and it is recommended to use plurals instead of verbs. The request method has already expressed the action meaning.
b) The URL path cannot be capitalized. If words need to be separated, use underscores uniformly.
c) The path is forbidden to carry a suffix indicating the request content type, such as ".json", ".xml", and it can be expressed through the accept header.
3) Request method: For the definition of specific operations, common request methods are as follows:
a) GET: fetch resources from the server.
b) POST: Create a new resource on the server.
c) PUT: Update resources on the server.
d) DELETE: Delete a resource from the server.
4) Request content: The parameters contained in the URL must have no sensitive information or meet security requirements; when the body contains parameters, the Content-Type must be set.
5) Response body: The response body can contain multiple data types, which are determined by the Content-Type header.
2. [Mandatory] The interface related to the front-end and back-end data lists is returned. If it is empty, an empty array [] or an empty collection {} will be returned.
Description: This agreement is conducive to more efficient collaboration on the data level and reduces many trivial null judgments at the front end.
3. [Mandatory] When an error occurs on the server, the response information returned to the front end must include
four parts: HTTP status code, errorCode, errorMessage, and user prompt information.
Explanation: The stakeholders of the four parts are browsers, front-end developers, error checkers, and users. Requirements for the prompt information output to the user
: short and clear, friendly prompt, guide the user to the next step or explain the cause of the error. The prompt information can include the cause of the error, context
, recommended operation, etc. errorCode: Refer to Appendix 3. errorMessage: Briefly describe the cause of the backend error, which is convenient for troubleshooting
personnel to quickly locate the problem, and be careful not to include sensitive data information.
Positive example: Common HTTP status codes are as follows
1) 200 OK: Indicates that the request is successfully completed and the requested resource is sent to the client.
2) 401 Unauthorized: The request requires authentication, which is common when login is required but the user is not logged in.
3) 403 Forbidden: The server refuses the request, which is common in situations where confidential information is copied or other login user links are copied to access the server.
4) 404 Not Found: The server cannot obtain the requested webpage, and the requested resource does not exist.
5) 500 Internal Server Error: Internal server error.
4. [Mandatory] In the JSON format data for front-end and back-end interactions, all keys must be in
lowerCamelCase style starting with a lowercase letter, which conforms to English expression habits and has complete meaning.
Positive example: errorCode / errorMessage / assetStatus / menuList / orderList / configFlag
Negative example: ERRORCODE / ERROR_CODE / error_message / error-message / errormessage /
ErrorMessage / msg
5. [Mandatory] errorMessage is the embodiment of the front-end and back-end error tracking mechanism. It can be output to the type="hidden"
text control on the front-end, or to the log of the client to help us quickly locate the problem.
6. [Mandatory] For scenarios that need to use very large integers, the server will always use the String string type to return, and the
Long type is prohibited.
Note: If the Java server directly returns Long integer data to the front end, JS will automatically convert it to Number type (Note: This type is a double-
precision floating-point number, and its representation principle and value range are equal to Double in Java). The maximum value that the Long type can represent is 2 to the 63rd power
-1. Within the value range, when the value exceeding the 2 to the 53rd power (9007199254740992) is converted into a JS Number, some values
will lose precision. Explanation: Within the value range of Long, any integer with a power of 2 will never have precision loss, so
precision loss is a probability issue. If the mantissa and exponent bits of a floating-point number are unlimited, any integer can be represented exactly, but unfortunately, the
mantissa of a double-precision floating-point number is only 52 bits.
Counter-example: Usually when the order number or transaction number is greater than or equal to 16 digits, there is a high probability that the front-end and back-end documents will be inconsistent. For example, "orderId": 362909601374617692, but the value obtained by the front-end is: 362909601374617660
.
7. [Mandatory] HTTP requests cannot exceed 2048 bytes when passing parameters through the URL.
Note: Different browsers have slightly different restrictions on the maximum length of the URL, and the processing logic for exceeding the maximum length is also different. 2048
bytes is the minimum value of all browsers.
Counter-example: A business passes the return item id list in the URL as a parameter. When there are too many items to return at one time, the URL parameter is too long, and the parameters passed to the
backend are truncated, resulting in some items not being returned correctly.
8. [Mandatory] When the HTTP request transmits content through the body, the length must be controlled. If the maximum length is exceeded, the backend parsing error will occur
.
Note: The default limit of nginx is 1MB, and the default limit of tomcat is 2MB. When there is a business that needs to transmit larger content, you can increase the
limit on the server side.
9. [Mandatory] In the page turning scenario, if the user input parameter is less than 1, the front end will return the parameters of the first page to the back end; if the back end finds that the parameter
input by the user is greater than the total number of pages, it will directly return the last page.
10. [Mandatory] The internal redirection of the server must use forward; the external redirection address must be
generated using the URL unified proxy module, otherwise the browser will prompt "insecure" due to the HTTPS protocol used online, and it will also cause URL maintenance
Inconsistent issues.
11. [Recommendation] The information returned by the server must be marked whether it can be cached. If it is cached, the client may reuse the previous request
results.
Description: Caching is beneficial to reduce the number of interactions and reduce the average latency of interactions.
Positive example: In http 1.1, s-maxage tells the server to cache, the time unit is seconds, the usage is as follows,
response.setHeader("Cache-Control", "s-maxage=" + cacheSeconds);
12. [Recommendation] The data returned by the server should be in JSON format instead of XML.
Explanation: Although HTTP supports using different output formats such as plain text, JSON, CSV, XML, RSS and even HTML. If we
use user-oriented services, we should choose JSON as the standard data exchange format used in communication, including requests and responses. In addition,
application/JSON is a general-purpose MIME type, which is practical, concise, and easy to read.
13. [Recommendation] The time format of the front and back ends is unified as "yyyy-MM-dd HH:mm:ss" and GMT.
14. [Reference] Do not add the version number in the interface path, the version control is reflected in the HTTP header information, which is conducive to forward compatibility.
Note: When users repeatedly switch their jobs between lower versions and higher versions, the complexity of migration will increase, and there is a risk of data confusion.