API設(shè)計(jì)的一些心得總結(jié)
你做過API設(shè)計(jì)么？不管你是否做過API設(shè)計(jì)，都不妨看看老趙的這篇博文。在這篇文章中，老趙總結(jié)了自己進(jìn)行API設(shè)計(jì)的一些心得。
我平時(shí)的主要工作之一，便是編寫一些基礎(chǔ)及通用的類庫，能夠在項(xiàng)目中大量復(fù)用。換句話說，我的工作目的，是讓其他開發(fā)人員可以更好地完成工作。因此，如何設(shè)計(jì)更容易使用的API是我經(jīng)常要考慮的東西，偶爾也會(huì)有一些體會(huì)。而現(xiàn)在這些內(nèi)容，是我在為Functional Reactive Programing寫“參考答案”的時(shí)候忽然“總結(jié)”出來的想法。可能比較簡(jiǎn)單，但我想也是設(shè)計(jì)API是需要考慮的一些內(nèi)容。
在那篇文章里，我們是在為IEvent< T>對(duì)象提供一些封裝，其中會(huì)有MapEvent和FilterEvent等類型，為了方便調(diào)用，我們還定義了對(duì)應(yīng)的擴(kuò)展方法：
- public class MapEvent< TIn, TOut> : InOutEventBase< TIn, TOut>
- {
- public MapEvent(Func< TIn, TOut> mapper, IEvent< TIn> inEvent)
- : base(inEvent)
- {
- ...
- }
- }
- public class FilterEvent< TEventArgs> : InOutEventBase< TEventArgs, TEventArgs>
- {
- public FilterEvent(Func< TEventArgs, bool> predicate, IEvent< TEventArgs> inEvent)
- : base(inEvent)
- {
- ...
- }
- }
- public static class EventExtensions
- {
- public static MapEvent< TIn, TOut> Merge< TIn, TOut>(
- this IEvent< TIn, TOut> ev, Func< TIn, TOut> mapper)
- {
- ...
- }
- public static FilterEvent< TEventArgs> Filter< TEventArgs>(
- this IEvent< TEventArgs> ev, Func< TEventArgs, bool> predicate)
- {
- ...
- }
- }
MergeEvent和FilterEvent都是對(duì)另一個(gè)Event對(duì)象的封裝，您可以當(dāng)作一種裝飾器模式來考慮。不知您觀察到?jīng)]有，這個(gè)“待封裝”的Event對(duì)象在不同的地方（構(gòu)造函數(shù)或擴(kuò)展方法），出現(xiàn)的位置是不同的。在擴(kuò)展方法中，它是作為第一個(gè)參數(shù)出現(xiàn)在參數(shù)列表中，而在構(gòu)造函數(shù)中它則是第二個(gè)參數(shù)。對(duì)于擴(kuò)展方法來說，它是由語言規(guī)范強(qiáng)制得出的。但是在構(gòu)造函數(shù)中，這出現(xiàn)的順序完全可有由我們“自由”確定。那么，我們能否將待封裝的Event對(duì)象作為構(gòu)造函數(shù)的第一個(gè)參數(shù)呢？
自然是可以的，只是我在這里傾向于放在最后。原因在于這有利于API使用時(shí)的清晰。
假如我們沒有擴(kuò)展方法，也就是說只能使用構(gòu)造函數(shù)進(jìn)行“裝飾”，那么使用現(xiàn)在則是：
- var ev =
- new MapEvent< int, string>(
- i => i.ToString(),
- new FilterEvent< int>(
- i => i < 10,
- new MapEvent< DateTime, int>(
- d => d.Millisecond,
- ...)));
有的時(shí)候，我會(huì)將Lambda表達(dá)式寫在上一行，這樣可以讓代碼更為緊湊。那么如果MapEvent和FilterEvent都把待封裝的Event對(duì)象作為構(gòu)造和函數(shù)的第一個(gè)參數(shù)，又會(huì)怎么樣呢？
- var ev =
- new MapEvent< int, string>(
- new FilterEvent< int>(
- new MapEvent< DateTime, int>(
- ...,
- d => d.Millisecond),
- i => i < 10),
- i => i.ToString());
對(duì)比這兩者，在我看來它們的信息“呈現(xiàn)方式”是有顯著差距的。對(duì)于第一種情況（Event作為構(gòu)造函數(shù)最后一個(gè)參數(shù)），用戶看到這個(gè)定義時(shí)，從上到下的閱讀順序是：
- 構(gòu)造一個(gè)MapEvent對(duì)象，映射方式是XXX
- 包含一個(gè)FilterEvent對(duì)象，過濾條件是YYY
- 包含一個(gè)MapEvent對(duì)象，映射方式是ZZZ
而對(duì)于第二種情況（Event作為構(gòu)造函數(shù)的第一個(gè)參數(shù)）：
- 構(gòu)造一個(gè)MapEvent對(duì)象
- 包含一個(gè)FilterEvent對(duì)象
- 構(gòu)造一個(gè)MapEvent對(duì)象
- 最內(nèi)層MapEvent的映射方式為ZZZ
- 上一層FiterEvent……
- ……
第一種情況，API體現(xiàn)出的信息是流暢的，而第二種情況信息的體現(xiàn)是回溯的。第一種信息如“隊(duì)列”，而第二種如“棧”。第一種API閱讀起來用戶視線是單向的，而第二種API用戶可能會(huì)去努力尋找某個(gè)Lambda表達(dá)式到底對(duì)應(yīng)著哪個(gè)對(duì)象——就像我們?yōu)槭裁刺岢玦f/for不應(yīng)該嵌套太深，因?yàn)檎移ヅ涞拇罄ㄌ?hào)的確是件比較麻煩的事情。我想，應(yīng)該沒有會(huì)選擇把Event對(duì)象放在構(gòu)造函數(shù)參數(shù)列表的中間吧（如果有3個(gè)及參數(shù)），因?yàn)檫@會(huì)讓API調(diào)用看起來成“鋸齒狀”，實(shí)在不利于閱讀。
因此，在各種需要“裝飾”的場(chǎng)合，我往往都把“被裝飾者”作為構(gòu)造函數(shù)的最后一個(gè)參數(shù)。例如我在構(gòu)造DomainRoute的時(shí)候，便也是把innerRoute作為構(gòu)造函數(shù)的最后一個(gè)參數(shù)，由于DouteRoute所需要的參數(shù)較多，因此如果把innerRoute作為第一個(gè)參數(shù)，看起來會(huì)更加不便一些。同樣的，在之前設(shè)法“拯救C# 2.0”的時(shí)候也使用了這個(gè)做法。
當(dāng)然，這些是我個(gè)人的看法，并非所有人都是這樣做的。例如在.NET Framework中負(fù)責(zé)GZip壓縮的GZipStream對(duì)象，它的構(gòu)造函數(shù)便是將innerStream作為第一個(gè)參數(shù)出現(xiàn)。幸好，C# 3.0中已經(jīng)有了擴(kuò)展方法，如果使用構(gòu)造函數(shù)的話，即使信息再流暢，我想也不如擴(kuò)展方法來的直觀。因此，我一般都會(huì)利用擴(kuò)展方法，讓開發(fā)人員可以編寫這樣的API：
- dateEvent.Map(d => d.Millisecond).Filter(i => i < 10).Map(i => i.ToString())
- route.WithDomain("http://www.{*domain}/blogs", new { ... });
- stream.GZip(CompressionMode.Compress).Encrypt(...);
其實(shí)許多高級(jí)語言都會(huì)為了讓代碼寫的更易懂更清晰，因而提供一些看似“語法糖”的東西。例如F#中的|>操作符：
- let form = new Form(Visible = true, TopMost = true, Text = "Event Sample")
- form.MouseDown
- |> Event.merge form.MouseMove
- |> Event.filter (fun args -> args.Button = MouseButtons.Left)
- |> Event.map (fun args -> (args.X, args.Y))
- |> Event.listen (fun (x, y) -> printfn "(%d, %d)" x y)
其實(shí)|>操作符的目的只是把函數(shù)的最后一個(gè)參數(shù)調(diào)到之前來，但它能讓我們寫出“易讀”的代碼。例如FsTest類庫允許我們這樣寫：
- "foo" |> should equal "foo"
但其實(shí)，從理論上說，這種寫法完全等價(jià)于：
- should equal "foo" "foo"
正是因?yàn)橛辛藎>操作符，F(xiàn)#在這種情況下會(huì)將待封裝的Event對(duì)象作為函數(shù)的最后一個(gè)參數(shù)。這便是語言特性對(duì)API設(shè)計(jì)的影響。此外，F(xiàn)#中的“>>”以及Haskell的“.”可用“`”把一個(gè)函數(shù)作為中綴操作符來使用。但如果是Java這樣的語言，由于缺乏一些靈活的語法特性，開發(fā)人員就只能靠框架和類庫來構(gòu)建“Fluent Interface”來度過難關(guān)了（如Google Collections）。《卓有成效的程序員》一書中舉了這么一個(gè)例子，它們?yōu)橐粋€(gè)Car對(duì)象的構(gòu)造編寫了流暢接口：
- Car car = Car.describedAs().
- .box()
- .length(50.5)
- .type(Type.INSULATED)
- .includes(Equipment.LADDER)
- .lining(Lining.CORK);
以代替呆板的Java語法：
- Car car = new CarImpl();
- MarketingDescription desc = newMarketingDescriptionImpl();
- desc.setType("Box");
- desc.setSubType("Insulated");
- desc.setAttribute("length", "50.5");
- desc.setAttribute("ladder", "yes");
- desc.setAttribute("lining type", "cork");
- car.setDescription(desc)
似乎程序員永遠(yuǎn)不會(huì)放棄這方面追求：編寫更清晰，更易懂的代碼。
【編輯推薦】
