【API】API设计优秀思想汇总

1，Apple子公司API结构设计杰出价值观汇整

Apple在WDDC开发人员讨论会数次传授API结构设计准则，能看出API结构设计是十分关键的，对Apple提倡的API准则都有什么样，他们列出呵呵：

https://swift.org/documentation/api-design-guidelines/swift.org/documentation/api-design-guidelines/

总的准则：

Clarity at the point of use is your most important goal。怎样检测API结构设计与否明晰：须要把它放到或者说的采用情景来检测（always examine a use case to make sure it looks clear in context）Clarity is more important than brevity。对比度比简约更关键Write a documentation comment for every declaration。假如你难以用单纯叙述API机能，或许你结构设计的API是严重错误的。

Naming：

Include all the words needed to avoid ambiguity。主要包括大部份单字防止模糊不清Omit needless words。删掉无须要的单字Name variables, parameters, and associated types according to their roles。依照配角展开重新命名

Strive for Fluent Usage：

中心价值观：表达式的重新命名和模块形成两个意欲的句法语句，除此之外透过表达式和方式重新命名差别与否具有side-effects。

Use Terminology Well：

Avoid obscure termsStick to the established meaningAvoid abbreviations.Embrace precedent.

Conventions：

Document the complexity of any computed property that is not O(1).Prefer methods and properties to free functions.Follow case conventionsMethods can share a base nameChoose parameter names to serve documentation.Take advantage of defaulted parameters when it simplifies common usesPrefer to locate parameters with defaults toward the endof the parameter list.

2，Joshua Bloch 提倡的API结构设计思路

http://www.cs.bc.edu/~muller/teaching/cs102/s06/lib/pdf/api-design?spm=ata.13261165.0.0.38067cd1w5lGp5www.cs.bc.edu/~muller/teaching/cs102/s06/lib/pdf/api-design?spm=ata.13261165.0.0.38067cd1w5lGp5

好的API具有的特征：

Easy to learn Easy to use, even without documentation Hard to misuse Easy to read and maintain code that uses it• Sufficiently powerful to satisfy requirements Easy to extend Appropriate to audience

基本准则：

API Should Do One Thing and Do it WellAPI Should Be As Small As Possible But No SmallerImplementation Should Not Impact APIMinimize Accessibility of EverythingNames Matter–API is a Little LanguageDocumentation MattersAPI Must Coexist Peacefully with Platform

Class 结构设计准则：

Minimize MutabilitySubclass Only Where It Makes SenseDesign and Document for Inheritance or Else Prohibit it

Method结构设计准则：

Dont Make the Client Do Anything the Module Could DoDont Violate the Principle of Least AstonishmentFail Fast–Report Errors as Soon as Possible After They OccurProvide Programmatic Access to All Data Available in String FormOverload With CareUse Appropriate Parameter and Return TypesUse Consistent Parameter Ordering Across MethodsAvoid Long Parameter ListsAvoid Return Values that Demand Exceptional Processing

3, Boris Bokowski提倡的API结构设计思路

https://www.eclipsecon.org/2008/sub/attachments/API_Design_Workshop.pdfwww.eclipsecon.org/2008/sub/attachments/API_Design_Workshop.pdf

API用途：

Tell client what they need to know to use it Tell an implementor how to implement it Tell tester about key behaviors to test Determines blame in event of failure

结构设计准则：

No specs. No API.对API展开文档说明，如javadoc利用API Contract language：http://www.ietf.org/rfc/rfc2119.txt

API结构设计CheckList：

Introductory sentence summarizing purposePre-conditions Post-conditions Capturing of argument and result objects Specifying failure Side effects Concurrency Event ordering Callbacks Is the story complete, compelling, and seamless? Do all parts of the API pull their own weight?

三个层面API兼容性：

Contract compatibilityBinary compatiblesource compatible

4，Christian Kaestner API结构设计思路

主要价值观来自2中Joshua Bloch的API结构设计思路

https://www.cs.cmu.edu/~ckaestne/15214/s2017/slides/20170323-api-design.pdfwww.cs.cmu.edu/~ckaestne/15214/s2017/slides/20170323-api-design.pdf

Key design principle: Information hiding隐藏实现细节。

Define the scope of the API：Draft a specification, gather feedback,revise, and repeatWrite client code before you implement the API

5， IBM Java API结构设计思路

https://developer.ibm.com/technologies/java/articles/api-design-practices-for-java/developer.ibm.com/technologies/java/articles/api-design-practices-for-java/