API DESIGN（API设计）

原文链接为：http://tutorials.jenkov.com/api-design/index.html

 

结合项目对于API设计原则等进行了阐述。

 

Change is Expensive in the API's Public Interface
 Your API will most likely consist of public parts and private parts. The public parts are the parts of your API that the client of your API interacts with. This is also called the public interface.

If you change the public interface of your API you risk breaking code that uses your API. Your users won't like that. Therefore you should be really careful about doing this.

The private parts are less sensitive. You can change the internal parts almost all you like, as long as it does not affect how the API functions.
通常API有私有和公有部分组成，应该尽可能地避免改动用户使用的公有部分。
upfront Design

To avoid change as much as possible in the public interface of your API, spend a good deal of time analysing and designing how your API should function, and what the interface would look like.

Some of the issues you might want to think about could be:

    * How will the public interface look?
    * How will the API be configured?
    * What defaults should the API assume?
    * Should any of the API's abstraction layers be optional?

In fact, every topic touched upon in this tutorial trail on API design might be worth considering during the upfront design phase.

For my open source API's, Butterfly Components, I have spent a long time analysing what I wanted them to do, and how to get them to do, as well as about what public interface they should have. Even so, I have had to change the public interface a few times, to accommodate the requirements of the future, or correct the lacking analysis and design of the past.
为了避免对于API的经常变动，在设计的使用应该考虑：
公共的API接口如何展现？
API接口如何配置？
API应该默认的方式？
API的抽象层是否可选择的？
What to do When you do Need Change

If you find out that you really really need to change the public interface of your API, here is what you might consider doing:

   1. Provide an alternative interface, and leave the old interface in the API too.
   2. Deprecate the old interface to signal to users that they should switch to the new interface.

After a few releases with a deprecated interface you might consider removing it completely. But give users of your API a chance to upgrade at their own pace.

如何改动API接口
（1）提供可选的接口，保留旧的API；
（2）提示就的API已经过时，用户应该使用新的接口。（经过几次更新以后，应该彻底的舍去过时的API）

API Design: Keep it Small and Focused

API设计应该保持小而精
Avoid "Commons" API's
应该避免"utility" class or package.

API Design: Don't Expose More than Necessary
API设计不应扩展需求
API Design: Provide Sensible Defaults
API设计应该设定合理的默认
API Design: Optional Abstractions
API设计应该具有合理的抽象层

API Design: Central Point of Access

API Design: Don't Force the User to Assemble Components

API Design: Avoid External Dependencies

API Design:Avoid Logging