1 Purpose
Stable and reliable, reduce costs and increase efficiency
The front-end and back-end data transmission protocols are designed to improve system stability and reliability, and reduce the online and offline bug rate. And improve R&D efficiency, reduce communication costs, and reduce delay rates. It is one of the important specifications to ensure the smooth development of the front-end and back-end of the project, and defines the rules and standards for the interaction between the front-end and the back-end.
2 Data Transfer Conventions
2.1 Data is transmitted to the backend and circulated at the frontend
1. Front-end URL parameters: In principle, only id parameters are allowed, and Chinese parameters and related status judgment parameters are not allowed to be passed into the URL.
2. Data submission: Clarify the form data type, including whether it is required to check, multipart data, and other complex types of data.
3. Parameter specification: describes the parameters required by the API in detail, including the parameter name, type, whether it is required, default values, and examples.
2.2 Data is returned from the backend to the frontend
1. Normal data format: You need to define the format of single data, complex data, possible data, no data, paginated data, verification data, special data, and authentication encrypted data.
2. Abnormal data format: It must contain the abnormal status code, abnormal name, data format, error type code, abnormal location, and abnormal description, so that the front-end can correctly process and display the error information.
3. Performance requirements: performance indicators such as response time, concurrent processing capacity, robustness, stability, fault recovery, and security of the interface.
[Measures]
• Scaffolding unification, construction projects, etc.
•Error code standard: Establish a unified standard code code display corresponding to HTTP code, and identify the error code content (rules, default rules for the number of digits) and format.
3. Document communication specifications
Front-end and back-end service interfaces should be documented to ensure that interfaces and documentation are developed before front-end development, so that developers can accurately understand and use the interface. The document should contain details such as the interface address, request method, request parameters, and return result. The request method and return result shall be determined according to the product logic.
1. RESTful API design style: This is an API design style based on the HTTP protocol, which makes the interface design more concise and clear by using HTTP verbs, URIs, and HTTP status codes to represent the operation of resources and the results of requests.
2. URL specification: the URL structure of the interface, including the basic path, interface name, and parameter passing method (such as query parameters, form data, and request body in JSON format).
3. Interface version control: In order to ensure the compatibility and maintainability of the interface, the interface can be versioned if necessary. You can add a version number to the URI or use the request parameter to distinguish the version information.
4. Parameter delivery method: Clarify the method of parameter transmission, including GET, POST, PUT, DELETE, etc., as well as the format of parameters (such as JSON, form, etc.).
5. Result format: The API should use a unified format for the return result, including status codes, error messages, and data. It is recommended to use the JSON format to facilitate the representation of complex data structures.
[Measures]
•Unified and promoted interface documentation tools: Japi or Tibetan Pavilion can be determined
4 Schema design and data structure
4.1 Front-End Rules
1. Experience first: Optimize the user experience operation steps as much as possible, meet product requirements, and put forward interactive suggestions in a timely manner.
2. SDK version maintenance: When multiple systems call front-end addresses or SDKs, version maintenance is required, and it is best to fix special versions in special scenarios, and strictly control the upgrade of general versions.
3. Anti-shake throttling: The front-end requests the anti-shake policy and function throttling policy.
4. Code merging: When merging code into the main branch, be sure to ensure that your code is based on the code pulled by the latest commit of the main branch (you can pull a hotfix branch from main first, merge with the hotfix branch first, and then merge to the main branch).
[Measures]
•Line cloud code merge detection.
•Add version number and strict version management.
4.2 Architecture design
1. Decoupling of architecture design and code implementation: Architecture design designs the architecture scheme, data transmission interaction, technology selection, and logic scheme of system functions according to product logic; Code implementation mainly focuses on specific program coding, specification, and specific data processing.
1. Front-end logic extensibility: The front-end design is based on the interaction logic of the product, and the extensibility of the interaction logic needs to be considered; Pay attention to the problem of deep copy in data processing.
1. Ease of use of back-end interface: The back-end design can be customized according to its own requirements, but the data structure given to the front-end interface needs to be based on the product business logic.
2. Front-end and back-end separation: Agree on the data structure in advance and develop according to the data structure.
3. If the front-end directly exposes the public network, it is necessary to take security precautions to prevent XSS, CSRF and other attacks, and encryption and decryption of sequels involving data privacy, transmission, and attacks. The backend interface needs to be protected against SSRF attacks.
[Measures]
• Front-end coupling system to do separation (development separation, release separation)
•Key type rules: enumeration types of key core data, such as amount and time.
4.3 Data structure design
1. Constant data structure: The fields and types agreed on the front and back end should not be easily changed, and if there is any change, the other party should be informed in advance.
2. Robust marginal design: The interface needs to consider the definition of extreme cases, and the definition must be clear (for example, when different types of fields are empty, null, infinite, negative, etc.).
3. Concise data structure: The data interface fields should be as clear, simple, as few as possible, as few as possible, as few as possible, and extensible.
4. Data type consistency: Consistency of front-end and back-end data types.
5. [Special Convention]: The backend cannot accept the front-end value with the int type (the default value of int is 0); If you receive the Int type, be sure to handle the exception in the package.
4.4 Safety and Robustness
1. Front-end and back-end interface data verification: For important data transmission (such as cost funds, etc.), the back-end must do interface verification, and the front-end needs to do logical verification (and even encryption and decryption mechanism); It also includes the back-up processing and early warning used by the third-party interface.
2. Request header convention: The frontend and backend should agree on the request header, instead of just using the system default (the default request header for data accepted by different versions of JDK may be different).
3. Interface consistency: the addition and modification of the same function should be the same interface as much as possible; If not, the reasons will be stated.
4. Logging: The interface logic needs to be clear and necessary for logging to facilitate query.
5. Interface anti-shake, idempotency: If necessary, the back-end service also needs to be anti-shake (such as the user clicks on a certain logic incorrectly, and quickly clicks on another logic, etc.).
6. Chaos experiments: If necessary, chaos engineering experiments need to be done to minimize the "explosion radius".
4.5 DSL Protocol
Select the classification policy of the SDL protocol based on the usage of Domain Specific Language (DSL). That is, the magnitude of compliance with the protocol is considered according to the complexity of the specific business logic.
•For scenarios that only display but do not modify, the front-end can directly prepare the DSL and save it to the server. For example, the graphical logic of CDP is displayed.
•For DSL data that needs to be used by both the front and back ends, divide the data into two parts, entity data and display data, as much as possible, and the front and back end need to jointly maintain the entity data; This is especially true for single-line process scenarios. Such as the process orchestration of the navigator.
•For more complex process logic judgment products that are used in both the front and back ends, different versions of DSL need to be maintained. Such as a slight canvas logic.
1. One set: The front and back end jointly maintain and parse the same set of data. Two parts: It is best to distinguish between front-end self-use fields and front-end and back-end public fields.
2. Agree on the rules and restrictions (length, etc.) for the front-end self-use fields.
3. Jointly agree on the rules for adding or decreasing common fields (types, levels, etc.).
4. In more complex scenarios, different versions or protocol versions can be used; You can also store only one part of the data, parse the front and back end separately, and maintain different versions.
{
code:'',或数字约定
data:{},
msg:''
}
Ideas
5 Ways of Practice
New project iterations
For new projects, it can be implemented directly according to specific needs in accordance with this specification. During the implementation process, the detailed rules of the specific product line can be obtained according to the actual situation of the demand.
Upgrade of old projects
1. For old projects, the front and back ends need to go through periodic self-inspection, especially for these core clauses that may directly affect the stability of the system, and must be strictly self-checked.
2. After self-inspection, record the corresponding hidden dangers in the system, and then make an update plan, which is best completed in the next iteration; If necessary, it can also be completed according to the Q or H dimension plan.
3. Other terms of the protocol should form the actual specification of the system as much as possible, and abide by the front and back ends together, so as to improve communication efficiency and reduce the bug rate.
6 Summary
The front-end and back-end data transmission agreement is a key link to ensure the smooth operation of Internet products, which involves data format, transmission mode, security and other aspects. This article focuses on the specific aspects of interaction.
In short, depending on the specific business and the continuous development of technology, we also need to constantly refine and improve these protocols in practice to adapt to new needs and challenges.
Brothers are welcome to exchange and discuss together