Design a high-quality API interface

Click on the official account , Practical technical articles Know in time

source ：blog.csdn.net/weixin_43318367/article/

details/108746057

Do you feel the same way ？

• docking XX When the business ,XX The functions and functions of the business API It's all up to the person in charge of business to ask repeatedly one by one 、 confirm . Which one to use API; How to use it? ; There are no restrictions ; wait

• Between businesses , Even in the same business ,API The style is not uniform .

  • API name ： Fully translated according to natural semantics ; Defined by attribute angle ; Defined by operating angle ; Verb object 、 Non verb object ; The plural 、 Non plural ; wait

  • API Enter the reference ： belt Map Of ; The same semantic field names are different ;

  • API The ginseng ： It's packaged Resoponse Of ; Directly return the result data ; Same data , The return format is different from the field name ;

  • error message ： Directly return the Chinese prompt ; Returns the code of the prompt message ; Returns the of the exception type ; wait

• XX Business API Performance unknown .

• As the business evolves , Open API Continue to increase , But there are many similarities

API Coding specification is imminent

good API The characteristics of

Self explanation

• from API You can understand it at a glance API What is it , Supported usage , Applicable scenarios , Exception handling, etc

Easy to learn

• Well documented , And provide as many examples and examples as possible copy－paste Code for .

Easy to use

• Powerful , But it's easy to use . Do not increase the use cost of the caller （ For example, the business party is required to use API Additional configuration and dependencies are required ）, Don't expose complex details 、 The lengthy use process gives the caller a sense of . The caller only makes the least perception and passes the least parameters .

Difficult to misuse

• first-class API It can be used directly by experienced developers API Without reading the documentation .

• Adequate static checks 、 Dynamic verification 、 Explicit exception description 、 Valid error tips .

API Design principles

1. Sufficiency principle

Not every function needs an interface , Nor is it necessary to add an interface for any requirement .

Every new interface , There should be sufficient reasons and considerations , That is, the existence of this interface is of great significance and value . Meaningless interfaces not only increase the difficulty of maintenance , More importantly, the controllability of the program is greatly reduced , The interface will also be very bloated .

2. The principle of single perspective

When designing interfaces , The angle of analysis should be unified . Otherwise, the interface structure will be confused . for example ： Don't design from a character's point of view , It's going to be designed from a functional point of view .

recommend ： With " Property object + Behavior " Definition of perspective API

3. Single function principle

Every API Interfaces should only focus on one thing , And do a good job . The product concept is simple 、 The relationship is clear . The function is ambiguous , Many special logical API Definitely not an elegant API, And will cause similar duplication of functions API.

notes ： If API It's hard to name , Then this may be a bad sign , A good name can drive development 、 And just split and merge the modules .

Functional API In flexibility 、 There must be a shortage of simplicity . Definition API Before the particle size , It is suggested to divide the business into fields first 、 Cross the border , To extract business objects , Then design a single function according to the business object use case API.

such as ： Search for members , In addition to querying the member table, you may also need to obtain other necessary information about the member , But don't query members and modify permissions and other similar business functions at the same time , It should be implemented in two interfaces .

4. Simple principle

The interface design is simple 、 Clear .API The functions performed can be very rich 、 Very powerful , but API Declaration and usage must be as simple as possible , The enrichment of functions cannot be realized through complex usage , This can lead to API It's not a single function , Evolution is uncontrollable .

The final review depends on API Ease of use .

• The example you wrote , Can you make your code look simpler ？

• Do you force the caller to pay attention to / Offer options they don't care about / To configure ？

• Are there any worthless additional steps ？

The code you write must be easy to read 、 Easy to understand , So that others will appreciate , It can also give you reasonable suggestions . contrary , If it's a complicated program , Others will always avoid it .

5. Abstract principle

API Input 、 The object described in the reference 、 attribute , It must be an entity abstracted according to business characteristics . Mistakenly reflect the concept of the underlying data model to API On . abstract API、 Abstract object entities are more macroscopic , With better applicability 、 Compatibility 、 Extensibility .

6. Compatible extension principle

Open to expansion , Turn off for changes . Guarantee API Backward compatibility of .

Extension parameters should be convenient , Ensure similar requirements in the future , Can be in the existing API It is realized through compatible expansion on .

7. The minimum surprise principle

The code should minimize surprises for readers . Business API Just design according to the requirements , There is no need to deliberately design complex and useless 、 Flashy API, To avoid self defeating .

8. Low coupling principle

API You should reduce dependencies on other business code . Low coupling is often a sign of perfect structural systems and excellent design .

The type of coupling ：

• The code implements business reverse call .

• Conditional logical dependency coupling . for example ： this API When dealing with the super order type of the national tax network , Events that need to be sent additionally to upload settlement payment vouchers MQ come out .

• coupling API Irrelevant business behavior . for example ： Purchase plan link log API When called , In the case of a project purchase order , Need to call the announcement additionally API Pull link information , Create a link log for this delegation .

9. Orthogonal principle

Orthogonality refers to changing one property without affecting other properties .

API The functions between should be orthogonal , No functional overlap .API There should be a complementary relationship between .

10. Easy to test principle

about API For callers ,API It should be testable and easy to test . test API No need to rely on additional environments 、 Containers 、 To configure 、 Public services, etc .

Friendly to testability API It is also a prerequisite for effective integration testing .

11. The principle of unity

API Have a uniform name 、 Unified entry / The specification of output parameters 、 Unified exception specification 、 Unified error code specification 、 Unified version specification, etc .

A unified standard API advantage ：

• Easy to be integrated by the framework 、 Handle

• be conducive to API The caller 、API Reuse of provider's development experience

• Avoid making mistakes , Avoid misuse

recommend

Main stream Java Advanced technology （ Learning material sharing ）

Java Interview questions

Join in Spring Technology development community

PS： Because the official account platform changed the push rules. , If you don't want to miss the content , Remember to click after reading “ Looking at ”, Add one “ Star standard ”, In this way, each new article push will appear in your subscription list for the first time . spot “ Looking at ” Support us ！