An article explaining how to write high-quality interfaces

clear needs

Requirements must be documented : Keeping documents facilitates learning and communication among members on the one hand and avoids word-of-mouth communication; on the other hand, it is also retained as evidence to facilitate later disputes, blame-shifting, etc. due to demands. Therefore, requirements documentation is important.

Requirements must be detailed : Communicate and confirm the requirements frequently, and do not be vague or ambiguous ; many times the requirements of the product are vague, and let the developers do it. There will be endless changes later, and the developers will take the blame, so the requirements must be detailed before proceeding. Start by sharpening your knife and chopping wood!

Be careful about the amount and quantity : usually, quantity-related values ​​are often related to money, inventory, etc., so data accuracy is very important. If the quantity is wrong, it will often lead to serious problems; therefore, for quantity-related values, is it allowed ? Negative numbers, how to determine the accuracy, what the calculation logic is, whether there are concurrent scenarios, etc. need to be clearly defined and corresponding measures taken to prevent errors.

Be careful when changing requirements (data) : In actual work, requirements (or data) may need to be changed due to incomplete consideration of requirements or operational errors by personnel. At this time, a simple modification of the product is enough, but the change may bring a lot of consequences. workload or risks; so do not accept casual product changes easily, carefully evaluate the workload and risks, and remember to give upward feedback when the risks are high .

abstract modeling

Analysis and abstraction : From a product perspective, the focus may be on functionality, but for development, the focus is on association and logic; therefore, rigid translation of functional requirements is often not good and can be easily changed later; it is better to think , abstracting logic and correlation relationships .

Draw UML/ER diagrams: assist thinking, abstract table relationships and required table fields

Review : If possible, ask colleagues with thorough business knowledge to review the data sheet; you can discover deficiencies in the design earlier and avoid pitfalls that have been stepped on by predecessors.

Database table creation

1. Try to follow the three paradigms of the database
2. Unify naming standards and character sets : Know the meaning by name, avoid using database keywords, unify standards, reduce ambiguity, and increase readability
3. Avoid over-design : for example, some redundant fields increase ambiguity and maintenance costs. Keep table fields few and precise.
4. Appropriate field type and length : Do not use too large a length, which will waste space; for numerical types, pay attention to accuracy issues
5. Try to use numeric types instead of character types : numeric types are more efficient, faster, and take up less space
6. Use Text/Blob types as little as possible: Text type processing performance is much lower than VARCHAR; pictures and other files should not be stored directly in the data table
7. Appropriate redundancy reduces table associations: For some information that does not change frequently, field redundancy can be used to reduce table associations and improve efficiency.
8. Evaluate which fields need to be indexed : a. Unique indexes can be created for some non-heavy fields; b. Indexes can be created for some fields that are frequently used to query or associate; c. The more indexes, the better, there are maintenance costs ; d. Differentiation It is not recommended to index fields with low degree of accuracy.
9. Try to set the field to not null : a. It can prevent null pointer problems; b. A null value may complicate the operation; c. You can keep not null by setting a default value;

Write optimized interface

1. Clarify requirements and top-level design : Understand the requirements, including basic functional requirements, as well as non-functional issues to be considered in the current scenario: such as data volume, concurrency, security, later changes and expansion, etc. Top-level design requires thinking about how to design interfaces from the overall perspective, and needs to consider design principles, design patterns, etc.
2. First meet the functional needs of the interface business: technology serves the business. The most basic thing is that the interface must meet the functional needs, followed by subsequent optimization.
3. When modifying an existing interface, pay attention to maintaining compatibility with the original one: when the current interface is called by other interfaces, modifying the interface may affect the whole body.
4. Pay attention to readability: reasonable comments, separated lines between code blocks
5. Reusability: extract common code, don’t repeat yourself, and facilitate subsequent unified modifications
6. Extract functions: Extract single functions into small functions to avoid overly long functions; make the hierarchy clearer and more readable
7. Extensibility: oriented to abstract design interfaces, consider whether some design patterns are applicable, etc.
8. Input parameter inspection: can avoid most errors caused by input parameters; use guard statements to fail quickly to avoid subsequent deeper errors.
9. Interface anti-duplication, current limiting, and anti-brushing : Some important interfaces, especially external interfaces, need to consider idempotence, interface anti-brushing, etc. depending on the scenario.
10. Exception and transaction processing : Handle exceptions correctly, whether it is necessary to customize exceptions, whether exceptions need to be forwarded, whether they are easy to locate; whether transactions need to be rolled back, what are the scenarios for transaction failure, whether the granularity of transactions should be considered, etc. These must be considered clearly
11. Traceable; record logs : Key operation information is recorded in logs to facilitate later tracing, positioning, and troubleshooting, and can be persisted if necessary.
12. Concurrent thread safety : Consider whether there are concurrency security issues in the interface. In concurrent scenarios, similar to "query + modification" scenarios, data inconsistency may occur; at this time, it is usually necessary to add locks and pay attention to the granularity of the locks, which will affect program performance
13. When calling third-party interfaces, consider exceptions, timeouts, retry strategies, etc.
14. Reasonable use of cache : space is exchanged for time. For scenarios where there is more reading and less writing, and low data timeliness requirements, using cache can improve query efficiency and reduce database pressure.
15. Reasonable use of batch operations: When batch operations are possible, do not use for loop calls; but for massive data, it must be divided into small batch operations and divide and conquer.
16. Use asynchronous with caution : If you encounter some operations that do not affect the accuracy of the core process but are time-consuming, you can consider using asynchronous to improve efficiency.
17. Use parallelism with caution : When performing multiple independent (no sequential) operations, you can consider using parallelism; make full use of the advantages of multi-core CPUs
18. SQL optimization : There are many interface performance issues, most of which are also SQL optimization issues. SQL optimization is also a big topic. You can study it in detail by yourself.

test interface

1. Unit testing : Test that each method executes normally without obvious exceptions. It may be a little troublesome, but it will get twice the result with half the effort.
2. Available functions: the most basic requirements, whether the core business process is smooth, normal prompts, and no obvious system abnormalities
3. Data accuracy : Whether the data meets expectations, data boundaries, accuracy, and calculation results are accurate
4. Transaction test : if an exception is thrown, whether rollback is required or normal, and whether the rollback granularity is full rollback or partial rollback
5. Concurrency security : Does the code have concurrency security issues? In high concurrency scenarios, is it idempotent, anti-brush, downgraded, normally available, and is the data correct, etc.
6. Performance test: In the case of high concurrency or massive data, whether the interface can respond normally and whether it meets the real-time requirements
7. Traceability : After the interface is executed normally and an exception is reported, is there any log or monitoring that can be traced back? It can be quickly located and the history of recurring operations has been checked.

Continuous refactoring

Exception feedback : When an exception occurs in testing or production, think about the cause of the exception and find ways to refactor to avoid recurrence, rather than just solving the current problem immediately ;

Daily refactoring : When developing functions on a daily basis, if you find that the previous code contains ill-considered, hidden bugs, etc., repair and optimize them in time ; according to Murphy's law, it may happen sooner or later; so deal with hidden problems in a timely manner BUG, avoid being in a hurry until a problem occurs.