API设计的一些心得总结

你做过API设计么？不管你是否做过API设计，都不妨看看老赵的这篇博文。在这篇文章中，老赵总结了自己进行API设计的一些心得。

10年的建平网站建设经验，针对设计、前端、开发、售后、文案、推广等六对一服务，响应快，48小时及时工作处理。成都全网营销推广的优势是能够根据用户设备显示端的尺寸不同，自动调整建平建站的显示方式，使网站能够适用不同显示终端，在浏览器中调整网站的宽度，无论在任何一种浏览器上浏览网站，都能展现优雅布局与设计，从而大程度地提升浏览体验。创新互联从事“建平网站设计”,“建平网站推广”以来，每个客户项目都认真落实执行。

我平时的主要工作之一，便是编写一些基础及通用的类库，能够在项目中大量复用。换句话说，我的工作目的，是让其他开发人员可以更好地完成工作。因此，如何设计更容易使用的API是我经常要考虑的东西，偶尔也会有一些体会。而现在这些内容，是我在为Functional Reactive Programing写“参考答案”的时候忽然“总结”出来的想法。可能比较简单，但我想也是设计API是需要考虑的一些内容。

在那篇文章里，我们是在为IEvent< T>对象提供一些封装，其中会有MapEvent和FilterEvent等类型，为了方便调用，我们还定义了对应的扩展方法：

 
 
 
      
  
  
  1. public class MapEvent< TIn, TOut> : InOutEventBase< TIn, TOut>  
    2.   
  
  
  2. {  
    3.   
  
  
  3.     public MapEvent(Func< TIn, TOut> mapper, IEvent< TIn> inEvent)  
    4.   
  
  
  4.         : base(inEvent)  
    5.   
  
  
  5.     {  
    6.   
  
  
  6.         ...  
    7.   
  
  
  7.     }  
    8.   
  
  
  8. }  
    9.   
  
  
  9.  
    10.   
  
  
  10. public class FilterEvent< TEventArgs> : InOutEventBase< TEventArgs, TEventArgs>  
    11.   
  
  
  11. {  
    12.   
  
  
  12.     public FilterEvent(Func< TEventArgs, bool> predicate, IEvent< TEventArgs> inEvent)  
    13.   
  
  
  13.         : base(inEvent)  
    14.   
  
  
  14.     {  
    15.   
  
  
  15.         ...  
    16.   
  
  
  16.     }  
    17.   
  
  
  17. }  
    18.   
  
  
  18.  
    19.   
  
  
  19. public static class EventExtensions  
    20.   
  
  
  20. {  
    21.   
  
  
  21.     public static MapEvent< TIn, TOut> Merge< TIn, TOut>(  
    22.   
  
  
  22.         this IEvent< TIn, TOut> ev, Func< TIn, TOut> mapper)  
    23.   
  
  
  23.     {  
    24.   
  
  
  24.         ...  
    25.   
  
  
  25.     }  
    26.   
  
  
  26.  
    27.   
  
  
  27.     public static FilterEvent< TEventArgs> Filter< TEventArgs>(  
    28.   
  
  
  28.         this IEvent< TEventArgs> ev, Func< TEventArgs, bool> predicate)  
    29.   
  
  
  29.     {  
    30.   
  
  
  30.         ...  
    31.   
  
  
  31.     }  
    32.   
  
  
  32. }  
    33.   
  
  
  33.  
    34.

MergeEvent和FilterEvent都是对另一个Event对象的封装，您可以当作一种装饰器模式来考虑。不知您观察到没有，这个“待封装”的Event对象在不同的地方（构造函数或扩展方法），出现的位置是不同的。在扩展方法中，它是作为第一个参数出现在参数列表中，而在构造函数中它则是第二个参数。对于扩展方法来说，它是由语言规范强制得出的。但是在构造函数中，这出现的顺序完全可有由我们“自由”确定。那么，我们能否将待封装的Event对象作为构造函数的第一个参数呢？

自然是可以的，只是我在这里倾向于放在最后。原因在于这有利于API使用时的清晰。

假如我们没有扩展方法，也就是说只能使用构造函数进行“装饰”，那么使用现在则是：

 
 
 
      
  
  
  1. var ev =  
    2.   
  
  
  2.     new MapEvent< int, string>(  
    3.   
  
  
  3.         i => i.ToString(),  
    4.   
  
  
  4.         new FilterEvent< int>(  
    5.   
  
  
  5.             i => i <  10,  
    6.   
  
  
  6.             new MapEvent< DateTime, int>(  
    7.   
  
  
  7.                 d => d.Millisecond,  
    8.   
  
  
  8.                 ...)));  
    9.   
  
  
  9.  
    10.

有的时候，我会将Lambda表达式写在上一行，这样可以让代码更为紧凑。那么如果MapEvent和FilterEvent都把待封装的Event对象作为构造和函数的第一个参数，又会怎么样呢？

 
 
 
      
  
  
  1. var ev =  
    2.   
  
  
  2.     new MapEvent< int, string>(  
    3.   
  
  
  3.         new FilterEvent< int>(  
    4.   
  
  
  4.             new MapEvent< DateTime, int>(  
    5.   
  
  
  5.                 ...,  
    6.   
  
  
  6.                 d => d.Millisecond),  
    7.   
  
  
  7.             i => i <  10),  
    8.   
  
  
  8.         i => i.ToString());  
    9.   
  
  
  9.  
    10.

对比这两者，在我看来它们的信息“呈现方式”是有显著差距的。对于第一种情况（Event作为构造函数最后一个参数），用户看到这个定义时，从上到下的阅读顺序是：

  1. 构造一个MapEvent对象，映射方式是XXX
  2. 包含一个FilterEvent对象，过滤条件是YYY
  3. 包含一个MapEvent对象，映射方式是ZZZ

而对于第二种情况（Event作为构造函数的第一个参数）：

  1. 构造一个MapEvent对象
  2. 包含一个FilterEvent对象
  3. 构造一个MapEvent对象
  4. 最内层MapEvent的映射方式为ZZZ
  5. 上一层FiterEvent……
  6. ……

第一种情况，API体现出的信息是流畅的，而第二种情况信息的体现是回溯的。第一种信息如“队列”，而第二种如“栈”。第一种API阅读起来用户视线是单向的，而第二种API用户可能会去努力寻找某个Lambda表达式到底对应着哪个对象——就像我们为什么提倡if/for不应该嵌套太深，因为找匹配的大括号的确是件比较麻烦的事情。我想，应该没有会选择把Event对象放在构造函数参数列表的中间吧（如果有3个及参数），因为这会让API调用看起来成“锯齿状”，实在不利于阅读。

因此，在各种需要“装饰”的场合，我往往都把“被装饰者”作为构造函数的最后一个参数。例如我在构造DomainRoute的时候，便也是把innerRoute作为构造函数的最后一个参数，由于DouteRoute所需要的参数较多，因此如果把innerRoute作为第一个参数，看起来会更加不便一些。同样的，在之前设法“拯救C# 2.0”的时候也使用了这个做法。

当然，这些是我个人的看法，并非所有人都是这样做的。例如在.NET Framework中负责GZip压缩的GZipStream对象，它的构造函数便是将innerStream作为第一个参数出现。幸好，C# 3.0中已经有了扩展方法，如果使用构造函数的话，即使信息再流畅，我想也不如扩展方法来的直观。因此，我一般都会利用扩展方法，让开发人员可以编写这样的API：

 
 
 
      
  
  
  1. dateEvent.Map(d => d.Millisecond).Filter(i => i <  10).Map(i => i.ToString())  
    2.   
  
  
  2. route.WithDomain("http://www.{*domain}/blogs", new { ... });  
    3.   
  
  
  3. stream.GZip(CompressionMode.Compress).Encrypt(...);  
    4.   
  
  
  4.  
    5.

其实许多高级语言都会为了让代码写的更易懂更清晰，因而提供一些看似“语法糖”的东西。例如F#中的|>操作符：

 
 
 
      
  
  
  1. let form = new Form(Visible = true, TopMost = true, Text = "Event Sample")  
    2.   
  
  
  2. form.MouseDown  
    3.   
  
  
  3.     |> Event.merge form.MouseMove  
    4.   
  
  
  4.     |> Event.filter (fun args -> args.Button = MouseButtons.Left)  
    5.   
  
  
  5.     |> Event.map (fun args -> (args.X, args.Y))  
    6.   
  
  
  6.     |> Event.listen (fun (x, y) -> printfn "(%d, %d)" x y)  
    7.   
  
  
  7.  
    8.

其实|>操作符的目的只是把函数的最后一个参数调到之前来，但它能让我们写出“易读”的代码。例如FsTest类库允许我们这样写：

 
 
 
      
  
  
  1. "foo" |> should equal "foo" 
    2.   
  
  
  2.  
    3.

但其实，从理论上说，这种写法完全等价于：

 
 
 
      
  
  
  1. should equal "foo" "foo" 
    2.   
  
  
  2.  
    3.

正是因为有了|>操作符，F#在这种情况下会将待封装的Event对象作为函数的最后一个参数。这便是语言特性对API设计的影响。此外，F#中的“>>”以及Haskell的“.”可用“`”把一个函数作为中缀操作符来使用。但如果是Java这样的语言，由于缺乏一些灵活的语法特性，开发人员就只能靠框架和类库来构建“Fluent Interface”来度过难关了（如Google Collections）。《卓有成效的程序员》一书中举了这么一个例子，它们为一个Car对象的构造编写了流畅接口：

 
 
 
      
  
  
  1. Car car = Car.describedAs().  
    2.   
  
  
  2.              .box()  
    3.   
  
  
  3.              .length(50.5)  
    4.   
  
  
  4.              .type(Type.INSULATED)  
    5.   
  
  
  5.              .includes(Equipment.LADDER)  
    6.   
  
  
  6.              .lining(Lining.CORK);  
    7.   
  
  
  7.  
    8.

以代替呆板的Java语法：

 
 
 
      
  
  
  1. Car car = new CarImpl();  
    2.   
  
  
  2. MarketingDescription desc = newMarketingDescriptionImpl();  
    3.   
  
  
  3. desc.setType("Box");  
    4.   
  
  
  4. desc.setSubType("Insulated");  
    5.   
  
  
  5. desc.setAttribute("length", "50.5");  
    6.   
  
  
  6. desc.setAttribute("ladder", "yes");  
    7.   
  
  
  7. desc.setAttribute("lining type", "cork");  
    8.   
  
  
  8. car.setDescription(desc)  
    9.   
  
  
  9.  
    10.

似乎程序员永远不会放弃这方面追求：编写更清晰，更易懂的代码。

【编辑推荐】

  1. C# 3.0新语言特性浅析
  2. 利用Visual C#和C#语言特性
  3. Jython入门指导：语言特性简介
  4. 比较几个JDK版本的新增语言特性
  5. 哪种语言将统治多核时代 再看函数式语言特性

当前标题：API设计的一些心得总结
URL分享：http://www.mswzjz.com/qtweb/news24/186474.html

网站建设、网络推广公司-创新互联，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 创新互联

猜你还喜欢下面的内容

软件开发知识

行业网站建设

成都集团网站建设　　 　航龙航空　　 　重庆联通机房托管　　 　小谭建站　　 　达州托管服务器　　 　企业网站设计　　 　网站SEO优化排名　　 　蓬溪网站建设　　 　宣传册设计　　 　成都定制高级网站建设　　 　娃娃鱼鱼苗　　 　成都网站建设　　 　梓潼做网站　　 　网站推广　　 　响应式网站建设　　 　外贸网站建设　　 　德昌麦琪建站　　 　绵阳电信机房　　 　腾讯云免备案主机　　 　东电技服