谈谈我所知道的API写法

谈谈我所知道的API写法

    如果经常阅读优秀框架源代码，那么你估计或多或少会对这个主题有一些自己的看法，特别当你作为一个架构师或者一个API的作者的时候你应该对这个主题有自己的真知灼见。我今天只是简单的根据他们的进化方式和自己的经验对他们分一下类，这仅仅是一家之言也许并不严谨，仅供参与/娱乐/交流。

客户端API

      这种客户端的API是大家最喜闻乐见的，说白了就是拿给人直接实现一个功能而调用的。这种API的写法要接受的考验主要是你的用户，因为你一个公开了这个API，谁也无法保证这个API到底使用没有。当然，你只能默认有人用了，所以说你能做的就是只增不减的暴露这个java类的功能来做到向后兼容。
    由于这种API无法收敛的性质，我们得不得保留以前版本关联的所有字段、方法和类型。也只有这样用户基于以前写的代码可以沿用并且更新后得到新的“惊喜”。说到这里，应该不难猜出这种API的写法了。
/**
 * This is a standard Client API format. 
 * 
It is "final" which means it doesn't accept any sort of extension
 *  one cannot cause binary Backward Compatibility problems by adding new methods into such class
 * 
Exposing only final classes to users of a ClientAPI makes it bullet-proof
 * 
 * @author Big Daydream
 *
 */
public final class ClientAPI {
     public final void methodVersion1(){
    //since 1.0 , modifier final is automatic   
     }
     
     public final void methodVersion2(){
    //since 2.0 , modifier final is automatic   
     }
}

提供者API

     这种API跟上面讲的最大的区别在于，它不仅仅是被调用的，他是用来给用户去实现的。这样的区别让它看起来更像插件或者SPI，然而他的的确确是API因为他跟客户API一样，一旦释放出来就不能收回了。
    这样的接口（不仅是语法上的接口，也可能是抽象类等）提供了给用户展现才华的基点，但它内部的调用策略是对用户隐藏的，我们可以在每个版本中控制它的调用方式。这种非final的语法特性决定了任意添加方法不是向后兼容的（据说JAVA8会提供这种语法支持 who knows？）。下面便是这样的API通用的写法：
/**
 * This is a recommanded format for ProviderAPI

 * 
 * The choice between the two interfaces clearly defines version which the provider implements.
 * One can use instanceof to check whether the provider implemented old contract only or also the new one.
 * According to result of the instanceof check, you can switch and behave .

 * 
 * Of course you don't want to spread instanceof calls all over the user's code. 
 * But if the ProviderAPIVersion1 interface is used only inside of ClientAPI,
 * then few additional instanceof checks don't harm any user of the ClientAPI 
 * (just the API writer, which is always a limited and thus acceptable damage).

 * 
 * The list of additional interfaces that can be implemented is sometimes hard to find.
 * As the previous code snippet shows, 
 * it helps if they are nested interface inside the most general (original) one. 
 * When the providers write their implementations,
 * they directly see all available extensions added in later revisions of the API.
 
 * 
 * @author Big Daydreamer
 *
 */
public interface ProviderAPIVersion1 {
        void methodVersion1();
  
  public  interface ProviderAPIVersion2 extends ProviderAPIVersion1{
       void methodVersion2();
  }
}

    但对于使用这个API的客户端，会有很多instanceof充斥代码空间，这样的确很恶心。一个提议就是将这些instanceof的判断移到一个utils类的静态方法里面，让用户去调用utils。