How to design an interface?

How to design an interface?

It is well known that an interface is a convention or specification that is provided for use by other modules or systems. Therefore, the interface must be guaranteed
Sufficient stability and ease of use. This is the basic requirement for designing interfaces.

1. Stability

The interface must be relatively stable, or it will cause the user and provider of the interface to constantly change the interface in order to adapt to the new interface
Implementation, may be repeated without hard work, serious impact on the entire software development progress. So how to ensure the design of the interface phase
For stability?
First, the semantics of the interface must be understood. Contains the type and name of the interface invocation method, interface name, and number of parameters. Abstract
The name of the interface or the number of participants is confusing or understanding the error. For example, the following example:
History::setattribute
Set the properties of the history and don't know what the interface is going to do at first. Unless there are many attributes of history, there is no
It is necessary to design this interface.
Ioctl
The IOCTL in the C library is actually very difficult to use because there are too many items to set, and the number of entries for each item is less consistent, and the interface makes
The pressure on the user is greater. However, the interface designers are forced to do so, because the application of IO configuration interface is more
, assuming that each setup interface provides an interface separately, it can result in very many interfaces, and the other is to ensure that the interface
For stability, the interface with abstract data facilitates portability and stability.
Therefore, an understanding of the interface semantics exception is that for accessibility, assuming that more interfaces are required, you can
into an interface that is differentiated by different parameters (as is the case with the definition of the form processing type in Windows).
Second, use the version number definition to differentiate between interfaces. For example, provide the interface version number query function, interface implementation provides
The query function for the interface version number.

2. Ease of Use

Interfaces are provided for use by third parties, and the more difficult interface will cause the user of the interface to complain.
Such as:
Setcookie (void* handle, const cookieparam& param);
GetCookie (void* handle, cookieparam& param);
The meaning of this interface name is still relatively clear, but the parameter cookieparam is too abstract and will cause the call of the interface
When using an interface, the value of the base data type must be composed of a cookieparam type, and then the ability to invoke the interface.
This is a bad interface design. It is neither easy to use nor easy for compiler optimization (pending confirmation).
Assume that the following interface is easier to use
Setcookie (void* handle, const url& URL, const string& cookie);
GetCookie (void* handle, const url& URL, String cookie);
Unless the number of interfaces exceeds 5, it is best to use the base data type as the parameter. Functions with more than 5 parameters
On the one hand, it is difficult for the caller, the combination of the number of parameters is too many, there is another aspect is not conducive to the compiler optimization of the use of
The number of register pass parameters.

3. How do I design an interface?

Adopt Ood idea, object-oriented idea, provide class interface or COM interface.
How is the C function interface designed? In fact, as with the C + + interface design principles, the idea of object-oriented is just
The class is designed to be a struct, and the public member function becomes a global function, and the private member function becomes the static function.
The first parameter of the function interface is equivalent to the this pointer in C + +.

4. Other requirements for interface design

* Normative: Mainly interface Design code specification, this is the most important requirement. At the same time consider the C interface named pollution
Problem. The General C interface is preceded by the identification of the company or module in front of the interface.
* Portability: For interfaces that need to be implemented on multiple platforms, consider the portability of the interface itself, so use least
For system-dependent types as either the parameter type of the interface or the return value type.
* Robustness: The interface needs to have moderate robustness, mainly refers to the interface can be in a variety of situations can achieve uniform efficiency
Causes the output of the interface to violate the interface semantics as a result of a change in the number of parameters passed in by the caller.
situation arises.
* Security: Interface definition needs to strictly restrict the read and write permissions, assuming that only the read-only parameters must be set
into a const to avoid illegal use.
* Compatibility: This is the principle of interface expansion, you must ensure that the same interface is implemented to be compatible with the previous version number of the use. Spread
The same interface can also be compatible with the implementation of the old interface.

5. How to extend the interface

1. Adopt version number feature, the interface implementation of different version number can agree with the difference, but provide version number query function;
2. The serial number indicates the new interface, such as Setcookie, SetCookie1, SetCookie2

How to design an interface?