如何设计接口？

本文最新地址：http://exbrowser.com/?p=449

    众所周知，接口是提供给其他模块或者系统使用的一种约定或者规范。因此接口必须要保
证足够的稳定性和易用性。这是设计接口的基本要求。

1.稳定性

    接口必须相对稳定，否则将导致接口的使用者和提供者为了适应新接口而不断修改接口
的实现，可能重复进行无用功，严重时影响整个软件开发进度。那么如何保证设计的接口相
对稳定呢？
    首先，接口的语义必须明确。包括接口调用方法、接口名称、参数的类型和名称。抽象
的接口名称或者参数名称使人困惑或者理解错误。如下例：
    History::SetAttribute
    设置历史记录的属性，初看不知道该接口要做什么。除非History的属性很多否则没有
必要设计这样的接口。
    ioctl
    C库中的ioctl，其实很难用原因是需要设置项太多，每个项的参数又不太一致，接口使
用者的压力就较大了。但是接口设计者也是不得已而为之，由于IO的设置接口的应用情况较
多，如果每个设置接口都单独提供一个接口则会导致非常多的接口，另外就是保证接口的相
对稳定，采用抽象的数据的接口便于移植和稳定。
    因此，明确的接口语义例外情况就是就是对于辅助功能，如果需要较多接口，则可以合
成一个接口，采用不同参数区分（如windows中的窗口处理过程类型的定义也是这种情况）。
    其次，采用版本定义来区分接口的差异。比如提供接口版本查询功能，接口实现着提供
接口版本的查询功能。

2.易用性

    接口是提供给第三方使用的，较难用的接口会导致接口使用者的抱怨。
    如：
        SetCookie(void* handle, const CookieParam& param);
        GetCookie(void* handle, CookieParam& param);
    此接口名称的意义还是比较明确的，但是参数CookieParam过于抽象，将导致接口的调用
者在使用接口时，需要将基本数据类型的值组成一个CookieParam类型，然后才能调用接口。
这是一种糟糕的接口设计。既不便于使用又不便于编译器优化（待确认）。
    如果该为下面的接口则较容易使用
        SetCookie(void* handle, const URL& url, const String& cookie);
        GetCookie(void* handle, const URL& url, String cookie);
    除非接口的参数个数超过5个，否则最好采用基本数据类型作为参数。超过5个参数的函数
一方面给调用者带来困难，参数排列组合的情况过多，另一方面就是不利于编译器优化时采用
寄存器传递参数。

3.如何设计接口？

    采用OOD思想，即面向对象的思想，提供类接口或者COM接口。
    对于C函数接口如何设计呢？其实和C++接口设计原则一样，也采用面向对象的思想，只是
将类设计成结构，公共的成员函数变为全局的函数，私有的成员函数变为static函数即可。
函数接口的第一参数就相当于C++中的this指针即可。

4.接口设计的其他要求

    * 规范性：主要是接口设计的代码规范，这是最基本的要求。同时考虑C接口命名污染的
              问题。一般C接口都会在接口前加上公司或者模块的标识。
    * 可移植性：对于需要在多平台实现的接口需要考虑接口本身的可移植性，因此最少使用
                对于系统依赖的类型作为接口的参数类型或者返回值类型。
    * 鲁棒性：接口需要有适度的鲁棒性，主要是指能够在多种情况下接口都能实现统一的效
              果，不会随着调用者传入的参数的变化而导致接口的输出出现违背接口语义的
              情况出现。
    * 安全性：接口定义时需要严格限制参数的读写权限，如果只能是只读的参数一定要设置
              成const，以免出现非法使用。
    * 兼容性：这是接口扩充的原则，必须保证同一个接口实现后向兼容前一版本的使用。扩
              充的同类接口也能兼容老接口的实现。

5.如何扩展接口 

    1.采用版本特性，不同版本的接口实现可以允许有差异，但是提供版本查询功能；
    2.序号表示新增的接口，如SetCookie、SetCookie1、SetCookie2