CN1609796A

CN1609796A - 应用编程接口（api）的设计

Info

Publication number: CN1609796A
Application number: CNA2004100826446A
Authority: CN
Inventors: A·J·摩尔; B·M·阿布拉姆斯; C·L·安德森; K·J·克瓦里纳; M·J·皮佐; R·A·布里罕姆
Original assignee: Microsoft Corp
Current assignee: Microsoft Corp
Priority date: 2003-10-23
Filing date: 2004-09-23
Publication date: 2005-04-27
Also published as: KR20050039534A; TW200515278A; CA2482374C; CO5610010A1; MY150179A; AU2004214614A1; TWI354928B; BRPI0404019A; SG111193A1; KR100952549B1; IL164070A0; MXPA04009835A; CA2482374A1; NO20043996L; EP1526449A3; NZ535482A; ZA200407484B; US7430732B2; RU2004130360A; EP1526449A2

Abstract

用于设计应用编程接口(API)的第一示例性方法实现包括：为核心场景准备多个代码样本，该多个代码样本的每一相应的代码样本对应于多个编程语言的一相应的编程语言；以及响应于该多个代码样本，从该核心场景衍生API。用于设计API的第二示例性方法包括：为特征区域选择核心场景；为该核心场景书写至少一个代码样本；以及响应于该至少一个代码样本衍生用于该核心场景的API。用于设计API的第三示例性方法包括：响应于对核心场景书写的至少一个代码样本衍生用于该核心场景的API；使用多个开发者在该API上执行一个或多个可用性学习；以及基于该一个或多个可用性学习修订该API。

Description

应用编程接口(API)的设计

技术领域

本发明一般涉及应用编程接口(API)，尤其涉及，作为示例而非局限，设计易于使用的API而同时提供控制和灵活性。

背景技术

应用编程接口(API)由开发者用于创建各种各样的应用和程序。开发者的范围从记录宏的办公室工作人员到低层设备驱动器作者。这些开发者依靠具有不同复杂度的不同语言和/或不同框架，而使用不同的技能组和/或为不同的目的来编程。传统地，设计了不同的API以不同的个别技能级别和对控制的不同需求(如基于不同的相关场景)为目标。

尽管该方法能够成功地提供为具体的开发者优化的API，它仍具有显著的不足。例如，多框架方法产生了开发者很难将知识从一个技能级别和场景类型转移到另一个的情况。当他们需要使用不同的框架实现场景时，开发者遭遇陡峭的(steep)学习曲线。并且不仅学习曲线极陡峭，而且它一般需要写入第一较低技能级别框架的代码必须被从无到有地写入第二较低技能级别框架中。此外，为不同的开发者技能级别创建单独的框架通常导致以一个级别开发者为目标或由其实现的API无法由另一级别开发者使用的情况。

图1示出了关于两种不同框架的传统API学习曲线的曲线图101。第一框架对应于具有相对较低级别的技能和/或难度要求同时伴之以由开发者控制的容量相对较低的框架。另一方面，第二框架对应于具有相对较高级别的所需要的技能和/或难度以及伴随的用于由开发者控制的相对较高容量的框架。这样的第一框架可由新手或偶尔为之的开发者使用，并且这样的第二框架可由有经验的或专业开发者使用。例如，第一框架可对应于为Visual Basic所设计的框架，而第二框架可对应于为C++所设计的框架。

在该传统方法中，设计并采用了相对分离且全异的API作为每一框架的一部分。跨越陡峭但相对较短的学习曲线来启用为相对较低技能级别和控制能力的第一框架的API使用。由于两个API框架的分离和全异特性，对第一框架的经验对于学习第二框架的第二API所贡献的知识很少，如果说有的话。因此，要跨越同样陡峭、甚至更高的学习曲线来启动第二框架的API的使用。

换言之，学习第一框架的API不能提供学习第二框架的API的垫脚石。这一脱节的API框架组的退步特性由连续性间隙指示。学习了第一框架的API的开发者并不能更便捷地学习第二框架的API，并且因此必须从第二框架的基础开始。

传统框架的另一问题是它们往往在任一情况下都具有总体较差的可用性。一般而言，“优化”面向对象设计/开发(OOD)方法(如，统一模型化语言(UML))是为了所得设计的可维护性，而不是所得框架的可用性。OOD方法更适合内部结构设计，但较不适合大型可重复使用库的API层的设计。例如，较差的可用性可根源于OOD方法仅关注在对较低功能块的提炼和/或贯穿整个API设计对严格的继承层次具有不动摇的忠诚度。

因此，需要能够至少改进传统API学习曲线的倒退连续性间隙和/或能够供应较好的整体API可用性的模式和/或技术。

发明内容

在第一示例性方法实现中，用于设计应用编程接口(API)的方法包括：为核心场景准备多个代码样本，多个代码样本的每一相应的代码样本对应于多个编程语言的相应的编程语言；以及响应于多个代码样本从核心场景衍生API。在第二示例性方法实现中，用于设计API的方法包括：为一特征区域选择核心场景；为该核心场景书写至少一个代码样本；以及响应于至少一个代码样本为核心场景衍生API。在第三示例性方法实现中，用于设计API的方法包括：响应于相对一场景书写的至少一个代码样本，为该场景衍生API；使用多个开发者在该API上执行一个或多个可用学习；以及基于该一个或多个可用学习修正该API。

本发明描述了其它方法、系统、途径、装置、设备、媒体、API、过程、排列等实现。

附图说明

贯穿附图，使用相同的标号标识相同和/或对应的方面、特征和组件。

图1示出了关于两个不同框架的传统API学习曲线的曲线图。

图2示出了关于两个级别的抽象的示例性有渐进API学习曲线的曲线图。

图3示出了API的示例性设计原理和实践。

图4所示是用于每特征区域设计API的示例性技术的流程图。

图5所示是用于每核心场景设计API的示例性模式的框图。

图6示出了以两个不同的目的为目标的示例性组件类型之间的潜在不一致性。

图7示出了被设计成可扩充和/或能共同操作以覆盖两个不同目的的组件类型之间的示例性关系。

图8示出了用于处理两层API的两个不同目的的示例性聚集组件(AC)和关联的分解类型(FT)。

图9示出了支持创建—设置—调用用法模式的示例性聚集组件和关联的API。

图10示出了能够(全部或部分地)实现设计和/或使用本发明描述的API的至少一个方面的示例性计算(或一般设备)操作环境。

具体实施方式

图2示出了关于两个不同的抽象级别的示例性渐进API学习曲线的曲线图200。所示的两个不同级别的抽象一个是相对高度抽象，一个是相对低度抽象。该高度抽象对应于其涉及所需技能和/或难度级别相对较低、且伴之以由开发者控制的容量相对较低的开发环境。另一方面，低度抽象对应于其涉及所需技能和/或难度级别相对较高、且伴之以由开发者控制的容量相对较高的开发环境。

示出渐进API学习曲线以相对平滑的方式从较低的需要技能和伴随的控制能力的一点处升起，通过高级和低度抽象的区域，到较高的需要技能和伴随的控制能力的一点。渐进API学习曲线呈现出高度抽象和低度抽象之间的连续区。一种集成的API框架可启用渐进的学习曲线。由于该API框架的集成特性，对高度抽象的经验向低度抽象以及需要更大控制的场景进行的API使用学习贡献了知识。

换言之，学习用于高度抽象的API向学习API和/或将API扩充到低度抽象中提供了垫脚石。这由包含高度和低度抽象区域的两层API框架形状指示。如后文所描述的，某些API的渐进特性令开发者能够最初使用简单的API，然后渐进地(并部分地)开始使用更复杂的API组件。由此，学习了以高度抽象为目标的API的开发者能够在其经验提供了某种保证和/或当他们所面对的场景的复杂度提出需要时转而使用以低度抽象为目标的API。

渐进API可以是易于使用(尤其在早期学习阶段)并且高度功能强大的(尤其是当随时间推移研究API时)。可使用的API可包括以下示例性属性的一个或多个：起步时需要少量概念和/或类、几行代码可实现简单的场景、类/方法具有直观的名字、自然的和/或明显的起点是显而易见的、并且有到另外需要的和/或相关的概念/类的清楚的(如可发现的)渐进。

渐进API也可启用从在较低难度和伴随的控制能力的一点处发展到较高难度和伴随的控制能力的一点的递增前进。下文描述了用于设计渐进API以及一般高度可使用的API的示例性范例。

图3在表300中示出了API的示例性设计原理和实践。表300指示四个示例性类别302-308的一般设计原理和实践。具体地，着眼于以下四个类别：场景驱动设计302、面向组件设计304、可定制默认值306和自编对象模型308。

当设计给定的API时，可采用用于指示的类别302-308的任一一个或多个的设计原理和实践。此外，在任一给定的类别302-308内，可实现所示的设计原理和实践的一个或多个。换言之，不需要为给定的API设计采用或实现每一类别或每一设计原理和实践。

场景驱动设计类别302示出了四个示例性设计原理和实践。首先，定义了所选择特征或技术区域的核心场景。第二，首先书写对应于该核心场景的代码样本，然后响应于该代码样本设计API。第三，设计上文介绍并在后文进一步描述的渐进API。第四，将使用定义的核心场景变得简单，并将使用其它场景变得可能。在后文“场景驱动设计”标题下的部分中进一步描述了场景驱动设计302。

面向组件设计类别304示出了三个示例性设计原理和实践。首先，创建聚集组件(AC)。一般地，聚集组件针对核心场景，它们相对简单且易于使用，并且在分解类型(FT)之上构建。分解类型更基础，并被分解成较低的逻辑层。这产生了一个两层的API设计。第二，这些聚集组件与分解类型相互关联。第三，支持创建—设置—调用用法模式，尤其对聚集组件。面向组件设计304在后文“面向组件设计”标题下的部分中进一步描述。

可定制默认值类别306示出了两个示例性设计原理和实践。首先，减少了至少使用聚集组件的所需要的初始化。默认值被用于减少所需要的初始化。第二，选择适合于定义的核心场景的默认值。可定制默认值306在后文“可定制默认值”标题下的部分进一步描述。

自编对象模型类别308示出了四个示例性设计原理和实践。首先，为核心场景保存了简单且直观的名字。第二，基于该组件类型的预期使用或目的，而非死板地坚持继承层次来选择名字。第三，抛出可执行行动的异常，使得开发者接收指示如何从异常消息修补错误的指令。第四，通过将偶尔使用的类型放置到子名字空间来生成干净的名字空间，以避免弄乱主名字空间。自编对象模型308在后文“自编对象模型”标题下的部分进一步描述。

场景驱动设计

在一描述的实施中，API规范由场景驱动。因此，API设计者首先书写API的用户必须要写入核心(如，主)场景的代码。API设计者然后设计对象模型来支持这些代码样本。该方法与开始设计对象模型(使用各种设计方法)并然后基于结果API书写代码样本相反。

换言之，尤其是对公共API设计，API设计者从用于每一特征或技术区域的场景的列表以及其代码样本开始，生成基于其的标题风格对象模型描述。特征区域的示例包括：文件I/O、网络化、消息通信、控制台(console)、诊断、数据库存取、网页、图形用户界面编程等等。

图4所示是用于按特征区域设计API的示例性技术的流程图。在块402，为给定的特征区域选择核心场景。例如，对于给定的技术区域，可选择前5-10个场景。可以基于最常用的功能(如，最常见的任务)或最频繁追踪的目标为给定的技术区域选择它们。例如，用于文件I/O技术特征区域的示例性场景是从文件读取和写入文件。

在块404，以多种语言(如两个或多个)为核心场景书写代码样本。例如，与所选择的核心场景关联的代码样本可以三种不同的语言书写。该代码样本可以三种语言实现当前选择的核心场景。这类语言包括，例如，VB、C#、MC++、标记语言等等；然而，也可以使用其它语言。如星号所指示的，应当理解，当为单个语言设计可使用且功能强大API时，可以单个语言为核心场景书写代码样本(或甚至一个以上代码样本)。

可以实现以多种语言书写代码样本，因为有时候以不同的语言书写的代码有显著的不同。在描述的实现中，用于当前选择的核心场景的代码样本使用具体语言的用户中常见的不同代码风格来书写(如，使用语言专用的特征或特性、使用开发者的惯例/习惯等等)，以该具体语言书写的具体的代码样本。例如，可使用语言专用包装来书写样本。例如，VB是对包装不敏感的，因此以VB书写的代码样本反映该可变性。另一方面，以C#书写的代码样本遵循其标准的包装。

另一示例涉及称为“使用”的语句，由C#支持。例如，“使用”调用封装尝试/最终(try/finally)块。然而，VB不支持该特征，并且书写代码样本可指示在尝试/最终语句中使用该特征对VB用户是笨拙的。再一示例涉及条件子句中的赋值，由C#支持。在文件I/O实例中，“if((text＝reader.ReadLine()！＝null)”在C#中起作用。然而，该赋值语句无法在VB的“if”子句中使用；相反，该代码被分裂为多个语句。又一示例涉及C#开发者使用参数化的构造函数的倾向，而VB开发者通常没有该倾向。例如，C#代码可以是“MyClass x＝new MyClass(″value″)”，而对应的VB代码为“Dim x As MyClass”以及“xProperty＝″value″”。

在块406，响应于以多种语言书写代码样本，从当前的核心场景衍生API。例如，从以多种语言的每一种书写的代码样本中收集的因素可结合进API中。这类因素可包括跨不同代码样本的类似性、两个或多个代码样本之间/之中的差异等等。这类因素以及块404和406的其它方面在下文参考图5进一步描述。

类似地，当为单个语言设计API时，响应于以单个语言书写的(多个)代码样本从当前的核心场景衍生该API。由此，从以单个语言书写的(多个)代码样本收集的因素可结合进该API中。作为用于单个或多个语言情况的另外的API设计因素示例，API设计因素可包括与面向为其书写(多个)代码样本的一种或多种语言的工具的兼容性。

在块408，确定该API是否过于复杂。例如，可由(多个)API设计者审阅该API来确定该API是否过于复杂。换言之，可执行初始检查来考虑是否能在不显著理解多个其它具体的API的情况下，在不进行不适当的试验的情况下等使用该API。这一初始检查也可核实衍生的API实际上能以每一相关语言在当前核心场景下起作用。如果该API太过复杂，则由设计者参考当前核心场景并响应于在块406中以多种语言书写的代码样本提炼该API。

另一方面，如果确定该API不是太过复杂(在块408)，则在块410，执行典型的开发者可用性学习。例如，可使用与典型的开发者通常使用的开发环境类似的开发环境来执行一个或多个可用性学习。这一普通的开发环境可包括智能感知(intellisense)、编辑器、语言以及由目标开发者组最广泛使用的文档集。

可用性学习

以很大范围的开发者为目标的可用性学习方便了场景驱动设计，尤其是当设计一般公共API的时候。由API设计者为核心场景书写的代码样本可能看似对他们简单，但是该代码样本可能对实际上目标的某些开发者组(如，尤其是新手和/或偶尔为之的开发者)不是同样的简单。另外，通过可用性学习储存的关于开发者处理每一核心场景的方式的理解可将提供对API的设计的强大的洞察力，以及它如何满足所有目标的开发者的需求。

一般地，可用性学习可在产品周期的早期执行，并且在对象模型的任一主要重设计之后再次执行。尽管这是一种成本较大的设计实践，它实际上能够从长远看来节省资源。在不引入中断的改变的情况下修补不可用或仅有缺陷的API的成本将是巨大的。

在块412，确认典型的开发者是否能够在没有重大问题的情况下使用API。例如，大多数对象应当能够在没有主要问题的情况下为当前选择的场景书写代码。如果他们无法书写，则修订该API(如后文参考块414描述的)。

重大/主要问题的解释由对给定的目标开发者组的可用性的期望的级别所决定。例如，测试对象对当前核心场景的详细API文档的频繁和/或广泛的引用可构成重大问题。一般，如果大多数测试开发者无法实现当前核心场景，或者如果他们所采取的方法与所期望的显著不同，则应当为可能的修订评估该API(直到并包括完整的重设计)。

如果确认典型的开发者无法在没有重大问题的情况下使用该API(在块412)，则在块414，基于来自可用性学习的经验修订API。例如，可改变默认值、可添加另一特性、可将一个或多个属性展现而不是封装，等等。

另一方面，如果确认典型的开发者能够在没有重大问题的情况下使用该API(在块412)，则在块416，对每一核心场景重复该过程。例如，对给定特征选择的诸核心场景中的另一核心场景变为为其书写代码样本(在块404)的当前核心场景。用于设计API的另一示例性示例更多地集中于两层API设计，在下文结合图8进一步描述。

图5所示是用于按核心场景设计API的示例性模式的框图404/406。所示的示例性模式对应于图4的块404和406，用于多语言实现。示出了用于第一语言的代码样本502(1)、用于第二语言的代码样本502(2)以及用于第三语言的代码样本502(3)。这三个代码样本502(1，2，3)的每一个都针对给定的当前核心场景。尽管示出了对应于三种语言的三个代码样本502(1，2，3)，可在该示例性多语言实现中替换地使用任意数量的目标语言的两个或多个代码样本502。

在描述的实现中，从以这三种语言的每一种书写的代码样本502(1，2，3)收集因素506。这些因素506被结合进API 504中。具体地，API 504被设计成支持以三种各自对应的语言书写的三个代码样本502(1，2，3)。然而，应当理解，因素506也可以应用到单语言实现。

以上参考图4的块404和406描述了一些示例性因素506，其它示例性因素506在图5的框图404/406中指示。这些因素506包括由代码样本502(1，2，3)的审阅所展现的语言专用命令。就以下示例代码行：“Foo f＝new Foo()；”描述了语言专用约束的一个示例。被设计成支持该示例行的渐进API必须包括默认构造函数；否则，该代码样本无法正确编译。

因素506也包括由语言特质和自然地倾向于不同语言的典型开发者的不同的技能/经验级别所引入的开发者期望。因素506还包括如可由代码样本502(1，2，3)的审阅发现的跨越不同语言的代码通用性和书写代码的惯例。

在考虑直接与不同语言有关的因素506的同时，还继续考虑了其它在此所描述的因素506。例如，以下因素506与以单个语言环境为目标的渐进API的有关，又与多语言环境的有关。首先，完成场景所需要的若干不同的组件类型是一个因素。一般地，需要的组件类型越多，学习起来就越难。第二个因素是代码的连续行之间的连接。一个组件类型的使用将开发者引向下一需要的组件类型的使用的程度，即该API更易于使用的程度。

第三，标识符的命名中的一致性是另一因素。第四个因素涉及特性、方法和事件的适当使用。第五个因素涉及对一个或多个现有API的可能的类似性。第六，另一因素涉及符合API的整体设计方针。第七个因素涉及该API是否与该框架的其它组件类型重叠。第八，与面向具体语言的工具的兼容性是再一因素。例如，VB开发者通常想要少参数的构造函数和特性设定函数。可替换地考虑其它因素506。

下文描述了涉及聚集组件和分解类型的相互关系的又一些其它因素506，特别参考图8。尽管图4和5的方法和模式可一般应用到设计API中，它们尤其可适用到设计双层API中。下文参考图6-8在“面向组件的设计”标题下的部分中描述了双层API范例(如具有聚集组件和分解类型)。

面向组件的设计

图6沿连续区(continuum)600示出了以两个不同目的为目标的示例性组件类型602之间的潜在不一致性。连续区600从左侧的高可用性区段延伸到右侧的高可控制性区段。多个组件类型602跨连续区600分布。

一般地，示出为相对较大的组件类型602标识较简单并因此较易于使用的类型。相反地，示出为相对较小的组件类型602标识较复杂并因此较难使用的类型。本上下文中的“简单”和“复杂”是指当实现指定的场景时具体的组件类型602的使用如何简单或如何困难。

示出为相对较小的组件类型602由于如下的若干示例性原因一般更难使用：首先，开发者具有他们应当使用哪些组件类型602的更多选择。在示出的示例中，与对较大组件类型602的三个“选择”相比，对较小组件类型602有14个“选择”。更具体地，开发者必须知道或看出，在各种组件类型602(HC)中使用哪一或哪些组件类型。这涉及理解多个组件类型602(HC)的每一个以及它们如何相互相关，这与从较少组件类型602(HU)中单个组件类型602(HU)开始相反。组件类型602(HU)和组件类型602(HC)之间的差异在后文进一步描述。

作为示例性类比，较小的组件类型602与立体声系统的个别组件相似；因此，用户必须知道需要哪一组件并如何将它们钩挂在一起。如果不将它们钩挂在一起，它们一般是没用的。较大的组件类型602与易于使用但是可能功能较不强大并且较不灵活的一体化立体声装置相似。较小的组件类型602较难使用的第二个原因是潜在地有更多的“出发点”。第三，一般有更多的概念要理解。第四，开发者必须理解个别的组件类型602如何与其它组件类型602相关。

在描述的实现中，组件类型602被划分成具有高可用性目的的组件类型602(HU)和具有高可控制性目的的组件类型602(HC)。高可用性组件类型602(HU)更简单且更易于使用，但是它们往往更不灵活、更限制和/或更有约束。它们一般可以在不具有整体API的广泛的知识的情况下使用。高可用性组件类型602(HU)通常能够实现有限数量的场景或最多对感兴趣的每一场景的有限数量的方法。

另一方面，高可控制性组件类型602(HC)的使用复杂，但是它们向开发者提供更大程度的控制。它们相对功能强大，并令开发者能够完成低层调节和调整。然而，使用高可控制行组件类型602(HC)开发需要许多组件类型602的更完整的理解，以启用正确地连接到实现甚至是相对直接的场景的多个高可控制性组件类型602(HC)的例示。

通常，高可用性组件类型602(HU)在诸如VB等介绍性语言中存在，而高可控制性组件类型602(HC)在诸如C++等高级专业程序员类型语言中存在。图6示出的高可用性组件类型602(HU)和高可控制性组件类型602(HC)之间的潜在不一致性至少部分地由图7的组件类型702改善。具体地，高可用性组件类型602(HU)和高可控制性组件类型602(HC)之间的相互关系由渐进API建立。

图7沿连续区700示出了被设计成可扩充和/或可相互操作以覆盖至少两个目的的组件类型702之间的示例性关系。在描述的实现中，具有高可用性目的的组件类型被实现为聚集组件602(AC)，而具有高可控制性目的的组件类型被实现为分解类型702(FT)。尽管组件类型702仅被划分成两个目的，然而可替换地它们被分割成三个或更多的目的(或其它类别)。

关键字704指示实线表示展现的分解类型之间的关系，而虚线表示封装的分解类型之间的关系。如图所示，聚集组件702(AC)(1)与三个分解类型702(FT)有关系。具体地，分解类型702(FT)(1)与聚集组件702(AC)(1)有展现分解类型的关系，分解类型702(FT)(2)和702(FT)(3)与聚集组件702(AC)(1)有封装分解类型的关系。

尽管未如此示出，但两个或多个聚集组件702(AC)可与同一分解类型702(FT)有封装的和/或展现的关系。展现的和封装的分解类型702(FT)和聚集组件702(AC)及其之间的关系在后文进一步描述，包括参考图8。

面向组件的设计涉及为每一用户概念提供单个对象，与每一逻辑概念需要多个对象相反。因此，聚集组件通常对应于用户概念，并且从可用性观点来看更简单。聚集组件层位于分解类型层之上。作为示例性比较，聚集组件可模型化诸如文件等事物，而分解类型可模型化诸如文件上的视图等事物的状态。聚集组件和分解类型一起为新开发者提供了渐进且逐步的学习曲线，尤其是关于具体的给定的API。

对聚集组件(aggregate component)的面向组件的设计

许多特征区域可得益于担当更复杂但较佳分解的剩余的特征区域API的简化视图的外表类型。在描述的实现中，外表覆盖了给定特征区域以及可任选的其它高级操作中前5-10个场景。聚集组件702(AC)可起这一外表类型的作用，而分解类型702(FT)可提供剩余的较佳分解的复杂API景象。

每一聚集组件将多个低层分解类捆绑到高层组件以支持最前的核心场景。例如，邮件聚集组件可与STMP协议、套接字、编码等捆绑在一起。一般地，每一聚集组件提供较高的抽象级别而非仅做事情的不同方法。提供简化的高级操作对不想学习由特征区域提供的功能的整体并仅希望在没有大量学习或API探究的情况下实现其经常是十分简单的任务的开发者来说是有益的。

一般地，面向组件的设计是基于构造函数、特性、方法和事件的设计。使用聚集组件是面向组件的设计的相对极端的应用。以下提供了用于聚集组件的面向组件的设计的一组示例性参数：

构造函数：聚集组件具有默认(少参数)的构造函数。

构造函数：对应于特性的可任选构造函数参数。

特性：大多数特性具有获取函数和设置函数。

特性：特性具有相当的(sensible)默认值。

方法：如果参数指定了跨方法调用(在选择的核心场景中)保持恒定的选项，则方法不采用该参数。这一选项可使用特性来指定。

事件：方法不将委托作为参数采用。回叫按照事件来实现。

面向组件的设计需要考虑如何使用API而非集中于在对象模型中纯粹引入方法、特性和事件上。用于面向组件的设计的一个示例性使用涉及用默认或相对简单的构造函数例示类型、在该实例上设置某些特性然后调用简单的方法的模式。该模式被称为创建—设置—调用用法模式。一般的示例如下：

‘VB

‘例示

‘Dim T As New T()

‘设置特性/选项

T.P1＝V1

T.P2＝V2

T.P3＝V3

‘调用方法；可任选地在调用之间改变选项

T.M1()

T.P3＝V4

T.M2()

当聚集组件支持这一创建—设置—调用用法模式时，聚集组件与聚集组件的主要用户的期望相一致。此外，为该用法模式优化诸如智能感知和设计程序等工具。示出创建—设置—调用用法模式的具体代码示例如下：

‘VB

‘例示

Dim File As New FileObject()

‘设置特性

File.Filename＝″c：\foo.txt″

File.Encoding＝Encoding.Ascii

‘调用方法

File.Open(OpenMode.Write)

File.WriteLine(″Hello World″)

File.Close()

采用作为渐进API的一部分的示例性聚集组件，设置“File.Encoding”特性是可任选的。如果未指定，则API具有预选择的文件编码的默认值。类似地，对于“File.Open()”，指定“OpenMode.Write”是可任选的。如果未指定，则采用API预选择的默认“OpenMode(打开模式)”

面向组件的设计的一个问题是它导致具有模式和无效状态的类型。例如，默认构造函数允许用户在不指定“FileName(文件名)”的情况下例示“FileObject(文件对象)”。在没有首先设置“FileName”的情况下尝试调用Open()(打开)导致异常，因为“FileObject”对于要打开是无效的状态(如，尚未指定文件名)。另一问题是可以被可任选并独立地设置的特性并不强制一致性以及对该对象的状态的原子变化。此外，这一“模态”性质抑制了消费者之间对象实例的共享，因为第一用户必须在重新使用它之前检查先前设定的值，以防万一第二用户在中间时期改变该值。然而，聚集组件的可用性对于大多数开发者来说比这些问题更重要。

当用户调用对象的当前状态中不有效的方法时，抛出“InvalidOperationException(无效操作异常)”。该异常的消息可清楚地解释需要改变哪些特性以将该对象放入有效状态。这些清楚的异常消息部分地克服了无效状态问题，并导致更自编的对象模型。

API设计者经常试图设计类型，使得对象无法在无效状态中存在。例如，这可以通过令所有需要的设置作为构造函数的参数、通过具有在例示后无法改变的设置的仅可获取(get-only)特性、通过将功能分隔成单独的类型使得特性和方法不重叠来实现。在描述的实现中，使用分解类型而非聚集组件来采用该方法。对于聚集组件，向开发者提供了向其传递无效状态的清楚的异常。当执行操作而非初始化组件(如，当调用构造函数或设置特性)时可以抛出这些清楚的异常，以避免无效状态是临时的，并且在随后的代码行中被“修补”的情况。

分解类型(Factored Types)

如上所述，聚集组件为大多数常见高级操作提供了快捷方式，并通常被实现为一组更复杂但也更丰富类型，称为分解类型上的外表。在描述的实现中，分解类型不具有模式，并且不具有十分明确的生存期。

聚集组件可提供通过某些特性和/或方法到其内部分解类型的访问。用户在相对高级的场景或需要与系统的不同部分的集成的场景中访问内部分解类型。由聚集组件使用的访问分解类型的能力令使用聚集组件书写的代码能够递增地为先进的场景添加复杂度，或与其它组件类型集成，而不需要集中在使用分解类型上从头开始重新写代码。

以下实例示出了展现其示例性内部分解类型(“StreamWriter”)的示例性聚集组件(“FileObject”)：

‘VB

Dim File As New FileObject(″c：\foo.txt″)

File.Open(OpenMode.Write)

File.WriteLine(″Hello World″)

AppendMessageToTheWorld(File.StreamWriter)

File.Close()

Public Sub AppendMessageToTheWorld(ByVal Writer As Stream Writer)

End Sub

高级操作

在描述的实现中，实现了作为上层或高层API(如，从抽象程度来看)的聚集组件，使得它们看似能够在用户不知道有时候在下面发生了一些复杂的事情的情况下“魔法般地”起作用。例如，“EventLog(事件记录)”聚集组件隐藏了记录具有读句柄和写句柄的事实，这两个句柄都要被打开以使用该组件。就开发者来看，聚集组件可以被例示、特性可以被设置并且可以在不关心底下功能的情况下书写记录事件。

在某些情况中，稍微更多的透明性可方便开发者的某一任务。一个示例是这样的操作，在其中用户采取显式行动作为操作的结果。例如，隐含地打开范文然后需要用户显式地关闭它可能是将“魔法般地”起作用的原理带地太远了。然而，勤奋的API开发者可经常能够设计甚至隐藏这些复杂度的聪明的解决方案。例如，读文件可被实现为打开文件、读其内容并关闭它的单个操作；由此，保护了用户免遭涉及打开和关闭文件句柄的复杂度。

此外，使用聚集组件不涉及实现任何接口、修改任何配置文件等等。相反，库设计者可采用已声明的接口的默认实现。此外，配置设置是可任选的，并由敏感(sensible)默认支持。

图8示出了用于处理具有双层API 800的两个不同目的的示例性聚集组件702(AC)和关联的分解类型702(FT)。聚集组件702(AC)表示第一或较高层，分解类型702(FT)表示第二或较低层。第一层采用自定义接口在第二层上有效地构建。

如图所示，聚集组件702(AC)包括多个聚集组件(AC)成员802。具体地，示出了聚集组件成员802(1)、802(2)、802(P)(1)、802(P)(2)、802(M)(1)、802(M)(2)和802(M)(3)。聚集组件702(AC)也包括展现的分解类型702(FT-Ex)以及封装的分解类型702(FT-En)。具体地，示出了展现的分解类型702(FT-Ex)(1)和702(FT-Ex)(2)，以及封装的分解类型702(FT-En)(1)和702(FT-En)(2)。分解类型702(FT)也包括分解类型(FT)成员804。

在描述的实现中，聚集组件702(AC)包括至少一个聚集组件成员802，例如，它可以是方法或特性。因此，聚集组件成员802可包括聚集组件方法802(M)和聚集组件特性802(P)。这些聚集组件成员802，如聚集组件成员802(1)和802(2)，可以对聚集组件702(AC)专用。换言之，某些聚集组件成员802，如聚集组件702(AC)上的聚集组件成员802(1)和802(2)可不依赖于任何分解类型702(FT)。可选地，某些聚集组件成员802可连接到基础分解类型702(FT)。

分解类型702(FT)可以是展现的分解类型702(FT-Ex)或封装的分解类型702(FT-En)。展现的分解类型702(FT-Ex)是在不使用或经历给定聚集组件702(AC)的个别聚集组件成员802的情况下可由或对其它一般组件类型702(FT或AC)访问的给定聚集组件702(AC)的分解类型702(FT)。如果分解类型702(FT-Ex/En)由聚集组件成员802(或者是方法或者是特性)返回，则展现该分解类型702(FT-Ex)。否则，封装该分解类型702(FT-En)。

换言之，聚集组件成员802可展现分解类型成员802，或者聚集组件成员802可返回分解类型实例。后者可在展现的分解类型702(FT-Ex)出现，前者可在封装的分解类型702(FT-En)出现。封装的分解类型702(FT-En)是包含在给定聚集组件702(AC)之内或对其为内部的给定聚集组件702(AC)的分解类型702(FT)。每一分解类型702(FT)可包括作为方法和/或特性的一个或多个成员804(其某些在图8中具体指示)。

如图所示，由聚集组件702(AC)展现了封装的分解类型702(FT-En)(1)的两个方法成员804，为方法成员802(M)(1)和方法成员802(M)(2)。由聚集组件702(AC)展现了封装的分解类型702(FT-En)(2)的一个方法成员804，为方法成员802(M)(3)。

展现的分解类型702(FT-Ex)(1)本身被展现为聚集组件702(AC)的特性成员802(P)(1)。类似地，展现的分解类型702(FT-Ex)(2)也被展现为聚集组件702(AC)的特性成员802(P)(2)。如图所示，展现了展现的分解类型702(FT-Ex)(1)的分解类型(FT)成员804以使其单独可访问(即，在不直接使用聚集组件702(AC)的个别成员802的情况下可访问)。因此，即使不由聚集组件702(AC)的聚集组件成员802个别地展现，展现的分解类型702(FT-Ex)的分解类型成员804仍可以被访问。

由此，展现了展现的分解类型702(FT-Ex)(1)的指示的成员804以使其在不使用其成员802的情况下可由对聚集组件702(AC)尾部的组件类型702访问。如从展现的分解类型702(FT-Ex)(1)发源的虚线所指示的，可“传送”(handed off)展现的分解类型702(FT-Ex)，以由不能与聚集组件702(AC)交互或者可单独使用传送的展现的分解类型702(FT-Ex)(1)来更好地达到其预期的目的的其它组件类型702(尤其是由其它分解类型702(FT))使用。应当注意，被“传送”的对象(展现的分解类型702(FT-Ex)(1))不是一个副本而是展现聚集组件702(AC)的一个实际的部分。结果，对传送对象的操作影响聚集组件702(AC)。

一般地，如果封装了分解类型702(FT)，则它不向消费者展现；相反，在聚集组件702(AC)上设置特性802(P)或调用方法802(M)可促使基础分解类型702(FT)上分解类型702(FT)被创建、特性804被设置或者方法804被调用。这些成员802和804可能不具有一对一的对应性；例如，在聚集组件702(AC)上设置若干特性802(P)可在聚集组件702(AC)中高速缓存。随后在聚集组件702(AC)上调用方法802(M)可促使将若干特性802(P)的先前指定的值用作对分解类型702(FT)的构造函数自变量来创建分解类型702(FT)。

在描述的实现中，聚集组件702(AC)除展现的分解类型702(FT-Ex)的展现之外，与更传统的面向对象组件在两种方式上不同。首先，聚集组件不必要展现其所有分解类型702(FT)的每一成员804。换言之，聚集组件702(AC)不严格地专用于继承层次。第二，聚集组件702(AC)可具有模式，并由此可周期性地具有导致无效操作的状态。

作为对关于因素506(图5)的面向组件设计的方针，在聚集组件702(AC)内展现或封装分解类型702(FT)可基于若干因素的一个或多个。首先，如果一个特定的分解类型702(FT)包括不由给定的聚集组件702(AC)展现的功能，则将该特定的分解类型702(FT)展现为给定聚集组件702(AC)的特性成员802(P)。第二，如果该框架的其它一般组件类型702可从对一个特定的分解类型702(FT)的直接消费的传送中获益，则将该特定的分解类型702(FT)展现为给定聚集组件702(AC)的特性成员802(P)。另一方面，当一个特定的分解类型702(FT)完全由给定的聚集组件702(AC)展现，并且当特定的分解类型702(FT)对向其它组件类型702的传送无用时，不展现特定的分解类型702(FT)(并因此它被封装)。

开发者可从聚集组件702(AC)开始，尤其是对于实现更简单和/或核心场景。当开发者想要或需要实现更复杂的场景时，开发者可递增并逐步地随时问开始直接访问并使用展现的分解类型702(FT-Ex)，包括其低层属性。依赖于较简单的聚集组件702(AC)的原始代码不需要被丢弃并且用完全依赖于分解类型702(FT)的更复杂的代码来替换。该API框架的两层可在各个部分中使用，并可同时共存。

设计双层API框架可以使用以下示例性技术来实现，它以十个阶段描述：首先，选择特定的特征区域的一组核心场景。其次，为选择的核心场景书写示出较佳的代码行的代码样本。第三，从代码行用适当的方法、默认值、抽象、命名等衍生聚集组件以支持该代码样本。

第四，依照衍生的聚集组件在适当时提炼来自第二阶段的代码样本。第五，评估提炼的代码样本是否足够简单。如果不是，则该技术再次在第三阶段继续。如果是，则在第六阶段确定是否存在另外的场景、使用、与其它组件的交互和/或其它需求。第七，API设计者判定第六阶段发现的任何另外的需求是否可被添加到聚集组件，而无需向选择的核心场景添加陡峭的复杂度。

第八，如果另外的需求不能被添加到聚集组件，则基于第七阶段定义分解类型的全功能组的理想分解(如，基于面向对象或其它分析方法)。第九，确定聚集组件如何并是否封装或展现来自第八阶段中定义的分解类型的功能。第十，在适当时提炼分解类型以支持聚集组件以及另外的需求。使用这一示例性技术，可设计具有聚集组件702(AC)和分解类型702(FT)的双层API框架。

图9示出了支持创建—设置—调用用法模式的示例性聚集组件702(AC)和关联的API 902、802(P)、802(M)和904。示出了以下示例性API组：构造函数902、特性802(P)、方法802(M)和事件904。采用创建—设置—调用用法模式，最初由开发者依赖于默认(如，少参数)构造函数902创建聚集组件702(AC)的实例。

第二，开发者设置任何默认值对其不合适和/或对对象的预期使用非较佳的任何特性802(P)。第三，由开发者调用期望的方法802(M)。然后按照事件904实现回叫。

可定制默认值

可定制默认值涉及只要至少对聚集组件可行就具有默认值。当例如采用对应于多种语言的多个代码样本设计API时，在每一代码样本中传递的同一值可替换地被设置为对该聚集组件的默认值。可定制默认值可通过设置聚集组件上的一个或多个特性来改变。

许多开发者更喜欢通过试错法来书写代码，而不愿意在开始项目之前花时间读文档并完全弄懂特征区域。这对新手和偶尔为之的开发者，如使用VB写代码的开发者而言尤其如此。这些开发者经常试图使用API来试验以发现它起什么作用以及怎样起作用，然后他们缓慢并递增地调整其代码直到该API实现达到其目标。编辑并继续方法的流行是该偏好的表现。

一些API设计将其本身给予“通过试验书写代码”，而一些则不这样。当使用通过试验书写代码方法时，有多个方面影响开发者可能具有的成功的级别。这些方面包括：(i)为手边的任务查找正确的API容易到何种程度；(ii)开始使用API，而无论它(最初)是否做了开发者希望它做或者不做的事情容易到何种程度；(iii)发现对API的定制点是什么容易到何种程度；(iv)发现对给定场景的正确的定制如何容易；以及(v)等等。

在描述的实现中，API被设计成需要很少的初始化(如最小的初始化量)，如果有的话。例如，可设计API使得具有单个参数的默认的一个或多个构造函数足够开始使用一个类型。当初始化必需时，不执行初始化导致的异常清楚地解释了需要完成和/或改变什么以移除或防止异常。例如，异常可规定需要设置什么或哪些特性。

作为示例而非局限，简略的规则是最简单的构造函数具有三个或更少的参数(上限为五)。另外，最简单的构造函数应当避免复杂类型作为任一参数，其中，复杂类型可以是其它分解类型或聚集组件。另一简略的规则是最简单的构造函数依赖于原语类型，如枚举、串、整型等等。类型也可实现多个复杂构造函数重载以支持多个复杂的场景。

简言之，API的可定制性可通过提供具有用于所有定制点的较佳默认值的特性来简化。(然而，开发者在定制其场景时一般应当能够向现有代码添加新代码；使用不同的API从无到有地重写代码应当是可任选的。)例如，系统消息通信队列聚集组件在向构造函数传递路径串并调用发送方法之后启用消息的发送。消息特性，如消息优先级和加密算法可通过向核心场景添加代码来定制。

自编对象模型

自编对象模型(Self documenting object model)涉及设计一种API框架，其中开发者可察看其对象和成员来了解它们并能够使用它们。例如，名字可基于一种类型如何期望被使用而非对许多开发者不希望学习的继承层次的投入。简言之，自编对象模型方便了将为开发者的那些人的可发现性。

如上所述，一些开发者更喜欢通过试错法来书写代码，并经常仅当其直觉无法实现其预期的场景时才读文档。由此，自编对象模型应当避免需要开发者在每次想要执行甚至简单的任务时读文档。以下呈现了帮助生成对描述的实现相对自编的直观API的一组示例性原理和实践。其任一一个或多个可以在给定的API和/或API设计实现中使用。

命名

第一个指导原理是为用户在大多数常见场景中需要使用(如例示)的类型保存简单且直观的名字。设计者经常“浪费”抽象的最佳名字，大多数用户不需要关心这些最佳名字。例如，如果期望是所有用户在他们能够开始使用API之前将必须理解该继承层次，则将一个抽象基类命名为“File(文件)”，然后提供一种具体的类型“XYZFile”能起较好的作用。然而，如果用户不理解该层次，则他们可能试图使用，并且通常是不成功的第一样东西是“File”类型。更具体地，为以最前的核心场景为目标的聚集组件保存了最常见或期望的名字，而较不常见或熟悉的名字在概念和抽象上使用。

第二个指导原理是使用清楚地规定每一方法完成什么以及每一类型和参数表示什么的描述性标识符名字。例如，API设计者在选择标识符名字时不应当犹豫会变得相当冗长。例如，可以看到“EventLog.DeleteEventSource(string source，stringmachineName)”相当冗长，但是它可论证地具有一纯的正可用性值。此外，类型和参数名字规定类型或参数表示了什么，而非它们完成了什么。方法名字规定方法完成了什么。当然，精确的冗长方法名字对具有简单且清楚语义的方法更容易，这是为何避免复杂语义是一种要遵循的较好的一般设计原理的原因。

指导设计实践是将关于命名选择的讨论作为API规范的审阅和/或测试的一个重要部分包括在内。示例性考虑和问题包括：大多数场景开始的类型是什么？当试图实现给定场景时大多数人首先考虑的名字是什么？常见类型的名字是用户首先考虑的名字吗？例如，由于“File”是当处理文件I/O场景时大多数人考虑的名字，因此用于访问文件的聚集组件可以被命名为“File”。另外，审阅并测试了最常用类型及其参数的最常用方法。例如，熟悉该技术，但是不熟悉考虑中的具体API设计的任何人能快速、正确并容易地识别并调用那些方法吗？

异常

如上所述，异常可方便自编API。换言之，API应当将用户引导至下一要做的事物，并且异常能够传递接下来所需要的事物并对其有益。例如，以下示例代码用消息“The′FileName′property needs to be set before attempting to open the′FileObject′(在试图打开‘FileObject’对象前需要设置‘FileName’特性)。”抛出了异常：

‘VB

‘例示

Dim File As New FileObject()

‘文件名未设置

File.Open()

强类型(Strong Typing)

用于方便直观API的另一指导原理是强类型。例如，调用“Customer.Name”比调用“Customer.Properties[′Name′]”更容易。此外，令这一“Name”特性将名字作为串返回比如果特性返回对象更有用。

有这些情况，期望具有基于串的访问函数的特性包(property bag)、后绑定(late bind)调用以及其它非强类型API，但是它们被归入稀有并且不是规则。此外，API设计者可为用户在非强类型API层上执行的更常见操作提供强类型助手。例如，消费者类型可具有特性包，但是它可另外为类似于“名字”、“地址”等更常见的特性提供强类型API。

向简易性矢量化

再一指导原理是为简易性而努力，尤其是对核心场景。标准设计方法针对生成为可维护性优化的设计，如通过使用抽象。因此，现代设计方法生成许多抽象。一个问题是这类设计方法在结果设计的用户将在开始实现甚至简单的场景之前变为该设计中的专家的假设上操作。然而，这通常不是真实世界的情况。

在描述的实现中，至少对于简单的场景，API设计者确保对象模型层次足够简单，使得它们能够在不需理解整个特征区域如何相互适合或相互操作的情况下被使用。所得设计优良的API可需要开发者理解所实现的核心场景，但是不需要对用于实现它的库的设计有完全的理解。

一般地，核心场景API被指向或对应于系统的物理或公知逻辑部件，而非抽象。对应于抽象的类型通常在不理解该特征区域的所有部分如何相互适合并相互操作的情况下很难使用；因此当需要交叉特征继承时它们更相关。

另一指导实践是当设计内部体系结构以及某些分解类型时，但不是当为核心或常见场景设计API(如具有聚集组件的API)时，使用标准设计方法(如，UML)。当为核心场景设计聚集组件时，作为替换采用了场景驱动设计以及原型化、可用性学习和迭代(如本发明上文所描述的)。

干净的名字空间

再一指导原理是(十分)少用的类型被放置在子名字空间中，以避免弄乱主名字空间。例如，以下两组类型可以从其主名字空间中分离：许可类型和设计类型。例如，许可类型可驻留在“.Permissions”子名字空间中，仅设计时(design-time-only)类型可驻留在“.Design”子名字空间中。

图1-9的行动、方面、特征和组件等在被划分成多个块的示图中示出。然而，描述和/或示出图1-9的顺序、相互连接、相互关系、布局等不应当被解释为局限，并且可以为设计API实现一个或多个系统、方法、设备、过程、媒体、API、装置、方案等任一方式修改、组合、重排列、增加、省略等任意数量的块。此外，尽管本发明的描述包括了对具体实现(以及图10的示例性操作环境)的引用，示出和/或描述的实现可以任一合适的硬件、软件、固件或其组合实现，并使用任一合适的软件体系结构、代码语言、场景定义、可用性学习格式等来实现。

计算机或其它设备的示例性操作环境

图10示出了能够实现如本发明所描述的用于设计API的至少一个系统、设备、装置、组件、方案、协议、途径、方法、过程、媒体、API、其某一组合等。操作环境1000可以在下文描述的计算机和网络体系结构中使用。

示例性操作环境1000仅为环境的一个示例，并非建议对可应用设备(包括计算机、网络节点、娱乐设备、移动器材、一般电子设备等)的使用或功能的范围的局限。也不应将操作环境1000(或其设备)解释为对图10所示的任一组件或其组合具有依赖或需求。

另外，设计API和/或从其起因的API可以使用众多其它通用或专用设备(包括计算系统)环境或配置来操作。适合使用的众所周知的设备、系统、环境和/或配置包括但不限于：个人计算机、服务器计算机、薄客户机、厚客户机、个人数字助理(PDA)或移动电话、表、手持式或膝上设备、多处理器系统、基于微处理器的系统、机顶盒、可编程消费者电子设备、视频游戏机、游戏控制台、便携式或手持式游戏单元、网络PC、小型机、大型机、网络节点、包括任一上述系统或设备的分布式或多处理计算环境、其某一组合等等。

API和/或从其起因的API的设计的实现可在处理器可执行指令的一般上下文环境中描述。一般地，处理器可执行指令包括例程、程序、模块、协议、对象、接口、组件、数据结构等等，执行和/或启用特定的任务和/或实现特定的抽象数据类型。如本发明的某些实现所描述的，设计API和/或从其起因的API也可以在分布式处理环境中实践和/或呈现，其中，任务由通过通信链路和/或网络连接的远程连接的处理设备执行。特别地但不是排他地在分布式计算环境中，处理器可执行指令可以位于单独的存储媒质上，由不同的处理器执行，和/或通过传输媒质传播。

示例性操作环境1000包括计算机1002形式的通用计算装置，它可包括具有计算/处理能力的任一(如电子)设备。计算机1002的组件包括但不限于，一个或多个处理器或处理单元1004、系统存储器1006以及将包括处理器1004的各种系统组件耦合至系统存储器1006的系统总线1008。

处理器1004不被从其形成的材料或其采用的处理机制所限制。例如，处理器1004可包括半导体和/或晶体管(如电子集成电路(IC))。在这一上下文中，处理器可执行指令可以是电子可执行指令。可选地，处理器1004或用于其的机制，并且由此计算机1002或用于其的机制可包括但不限于，量子计算、光计算、机械计算(如使用毫微技术)等等。

系统总线1008代表任一多种有线或无线总线结构类型的一个或多个，包括存储器总线或存储器控制器、点对点连接、交换结构、外围总线、加速图形端口、以及使用任一各种总线体系结构的处理器或局部总线。作为示例，这类体系结构可包括工业标准体系结构(ISA)总线、微通道体系结构(MCA)总线、增强ISA(EISA)总线、视频电子技术标准协会(VESA)局部总线、外围部件互连(PCI)总线，也称为Mezzanine总线、其某一组合等等。

计算机1002通常包括各种处理器可访问媒质。这类媒质可以是可由计算机1002或另一(如电子)设备访问的任一可用媒质，并包括易失和非易失、可移动和不可移动媒质，以及存储和传输媒质。

系统存储器1006包括易失存储器形式的处理器可访问存储媒质，如随机存取存储器(RAM)1040，和/或非易失存储器形式的处理器可访问存储媒质，如只读存储器(ROM)1012。基本输入/输出系统(BIOD)1014包含如在启动时帮助在计算机1002内的元件之间传输信息的基本例程，通常储存在ROM 1012中。RAM1010通常包含处理单元1004直接可访问和/或当前正在操作的数据和/或程序模块/指令。

计算机1002也可包括其它可移动/不可移动和/或易失/非易失存储媒质。作为示例，图10示出了对(通常)不可移动、非易失磁媒质(未单独示出)进行读写的硬盘驱动器或硬盘驱动阵列1016；对(通常)可移动、非易失磁盘1020(如“软盘”)进行读写的磁盘驱动器1018；以及对(通常)可移动、非易失光盘1024，如CD、DVD或其它光媒质进行读写的光盘驱动器1022。硬盘驱动器1016、磁盘驱动器1018和光盘驱动器1022的每一个通过一个或多个存储媒质接口1026连接到系统总线1008。可选地，硬盘驱动器1016、磁盘驱动器1018和光盘驱动器1022可以通过一个或多个其它的单独或组合的接口(未示出)连接到系统总线1008。

盘驱动器及其关联的处理器可访问媒质为计算机1002提供了处理器可执行指令，如数据结构、程序模块和其它数据的非易失存储。尽管示例性计算机1002示出了硬盘1016、可移动磁盘1020和可移动光盘1024，可以理解，其它类型的处理器可访问媒质可储存可由设备访问的指令，设备如磁带盒或其它磁存储设备、闪存、光盘(CD)、数字多功能盘(DVD)或其它光存储、RAM、ROM、电可擦除可编程只读存储器(EEPROM)等等。这类媒质也可包括被称为专用或硬布线的IC芯片。换言之，可以使用任一处理器可访问媒质来实现示例性操作环境1000的存储媒质。

多个程序模块(或指令/代码的其它单元或组，包括基于其的API框架和/或对象)可储存在硬盘1016、磁盘1020、光盘1024、ROM 1012和/或RAM 1040中，作为一般示例包括，操作系统1028、一个或多个应用程序1030、其它程序模块1032和程序数据1034。

用户可以通过输入设备，如键盘1036和定位设备1038(如，“鼠标”)向计算机1002输入命令和信息。其它输入设备1040(未具体示出)可包括麦克风、操纵杆、游戏垫、圆盘式卫星天线、串行端口、扫描仪和/或其类似物。这些和其它输入设备通过耦合至系统总线1008的输入/输出接口1042连接至处理单元1004。然而，输入设备和/或输出设备可替换地通过其它接口和总线结构连接，如并行端口、游戏端口、通用串行总线(USB)和红外端口、IEEE 1394(“火线”)接口、IEEE 802.11无线接口、Bluetooth(蓝牙)无线接口等。

监视器/察看屏幕1044或其它类型的显示设备也通过接口，如视频适配器1046连接至系统总线1008。视频适配器1046(或另一组件)可以是或可包括用于处理图形密集型计算并用户处理需要的显示需求的图形卡。通常，图形卡包括图形处理单元(GPU)、视频RAM(VRAM)等等，以方便图形的迅速显示和图形操作的性能。除监视器1044之外，其它输出外围设备可包括诸如扬声器(未示出)和打印机1048等组件，通过输入/输出接口1042连接至计算机1002。

计算机420可以在使用到一个或多个远程计算机，如远程计算装置1050的逻辑连接的网络化环境中操作。作为示例，远程计算装置1050可以是个人计算机、便携式计算机(如，膝上计算机、图形输入板计算机、PDA、移动站等等)、掌上或袖珍计算机、表、游戏设备、服务器、路由器、网络计算机、对等设备、另一网络节点或如上列出的另一设备类型等等。然而，示出远程计算装置1050为便携式计算机，可包括许多或所有此处相对计算机1002所描述的元件和特征。

计算机1002和远程计算机1050之间的逻辑连接被描述为局域网(LAN)1052和一般广域网(WAN)1054。这类网络环境常见于办公室、企业范围计算机网络、内联网、因特网、固定和移动电话网络、特别和基础结构无线网络、其它无线网络、游戏网络、其某一组合等等。这类网络和通信连接是传输媒质的示例。

当在LAN网络环境中实现时，计算机1002通常通过网络接口或适配器1056连接至LAN 1052。当在WAN网络环境中实现时，计算机1002通常包括调制解调器454或其它装置，用于通过WAN 1054建立通信。调制解调器1058可以对计算机是内置或外置的，通过输入/输出接口1042或任一其它合适的机制连接至系统总线1008。可以理解，示出的网络连接是示例性的，也可以使用在计算机1002和1050之间建立通信链路的其它装置。

在网络化环境中，如使用操作环境1000所示出的，描述的与计算机1002相关的程序模块或其它指令，或其部分可完全或部分地储存在远程媒质存储设备中。作为示例，远程应用程序1060驻留在远程计算机1050的存储器组件上，但是可由计算机1002使用或通过其访问。同样，为说明目的，此处示出应用程序1030和其它处理器可执行指令，如操作系统1028为离散的块，但是可以认识到，这类程序、组件和其它指令在不同的时刻驻留在计算装置1002(和/或远程计算装置1050)的不同存储组件中，并由计算机1002的处理器1004(和/或远程计算装置1050的处理器)执行。

尽管以对结构、逻辑、算法、功能和基于行动的特征的语言和/或示图描述了系统、媒质、设备、方法、过程、装置、技术、API、模式、途径。程序、方案和其它实现，可以理解，所附权利要求书中定义的本发明不必局限在所描述的具体特征或示图上。相反，解释了具体的特征和示图作为实现本发明的示例性形式。

Claims

1.一种设计应用编程接口(API)的方法，其特征在于，所述方法包括：

为核心场景准备多个代码样本，所述多个代码样本的每一相应的代码样本对应于多个编程语言的一相应的编程语言；以及

响应于所述多个代码样本，从所述核心场景衍生所述API。

2.如权利要求1所述的方法，其特征在于，它还包括：

由API设计者确定所衍生的API是否太过复杂。

3.如权利要求2所述的方法，其特征在于，它还包括：

如果所衍生的API被确定为太过复杂，则

由所述API设计者提炼所衍生的API以生成提炼的API。

4.如权利要求3所述的方法，其特征在于，它还包括：

由所述API设计者确定所提炼的API是否太过复杂。

5.如权利要求1所述的方法，其特征在于，它还包括：

使用多个开发者在所述API上执行一个或多个可用性学习。

6.如权利要求5所述的方法，其特征在于，所述执行包括：

使用所述多个开发者在所述API上执行所述一个或多个可用性学习，其中，所述多个开发者对所述多个编程语言是典型的。

7.如权利要求5所述的方法，其特征在于，它还包括：

断定所述多个开发者是否能够在没有重大问题的情况下使用所述API。

8.如权利要求7所述的方法，其特征在于，它还包括：

如果所述多个开发者不被断定为能够在没有重大问题的情况下使用所述API，则修订所述API。

9.如权利要求8所述的方法，其特征在于，所述修订包括：

基于来自所述一个或多个可用性学习的至少一个经验修订所述API。

10.如权利要求1所述的方法，其特征在于，所述衍生包括：

衍生所述API以支持分别对应于所述多个编程语言的所述多个代码样本。

11.如权利要求1所述的方法，其特征在于，所述衍生包括：

从所述多个代码样本收集语言专用命令；以及

将所述语言专用命令结合进所述API中。

12.如权利要求1所述的方法，其特征在于，所述衍生包括：

从所述多个代码样本收集语言启示的开发者期望；以及

将所述语言启发的开发者期望结合进所述API中。

13.如权利要求1所述的方法，其特征在于，所述衍生包括：

从所述多个代码样本收集通用性；以及

将所述通用性结合进所述API中。

14.如权利要求1所述的方法，其特征在于，所述衍生包括：

衍生所述API以具有将多个低层分解类型捆绑在一起以支持所述核心场景的聚集组件。

15.一种设计应用编程接口(API)的方法，其特征在于，所述方法包括：

为特征区域选择核心场景；

为所述核心场景书写至少一个代码样本；以及

响应于所述至少一个代码样本，衍生用于所述核心场景的API。

16.如权利要求15所述的方法，其特征在于，所述选择包括：

为所述特征区域选择多个核心场景。

17.如权利要求16所述的方法，其特征在于，它还包括：

对为所述特征区域所选择的多个核心场景的每一核心场景重复所述书写和所述衍生。

18.如权利要求15所述的方法，其特征在于，所述书写包括：

为所述核心场景书写多个代码样本，所述多个代码样本的每一相应的代码样本对应于多个编程语言的一相应的编程语言。

19.如权利要求18所述的方法，其特征在于，所述衍生包括：

响应于所述多个代码样本衍生用于所述核心场景的API。

20.如权利要求15所述的方法，其特征在于，它还包括：

使用多个开发者在所述API上执行一个或多个可用性学习；

断定所述多个开发者是否能够在没有重大问题的情况下使用所述API；以及

21.如权利要求20所述的方法，其特征在于，所述修订包括：

基于来自所述一个或多个可用性学习的至少一个经验修订所述API以生成修订的API。

22.如权利要求21所述的方法，其特征在于，它还包括：

对所述修订的API重复所述执行和所述断定。

23.如权利要求15所述的方法，其特征在于，所述衍生包括：

通过生成一包括一聚集组件和多个基础分解类型的双层API，衍生所述API以支持为所述核心场景书写的至少一个代码样本。

24.如权利要求15所述的方法，其特征在于，所述衍生包括：

从所述至少一个代码样本收集一个或多个语言专用命令；以及

将所述一个或多个语言专用命令结合进所述API中。

25.如权利要求15所述的方法，其特征在于，所述衍生包括：

如果一特定的分解类型的所有成员由与所述核心场景关联的聚集组件展现，将所述特定的分解类型封装到所述聚集组件中。

26.如权利要求15所述的方法，其特征在于，所述衍生包括：

如果一特定的分解类型对其它组件类型是独立地不感兴趣的，则将所述特定的分解类型封装到与所述核心场景关联的聚集组件中。

27.如权利要求15所述的方法，其特征在于，所述衍生包括：

如果一特定类型的至少一个成员不由与所述核心场景关联的聚集组件展现，则从所述聚集组件展现所述特定的分解类型。

28.如权利要求15所述的方法，其特征在于，所述衍生包括：

如果一特定的分解类型可以由另一组件类型独立于与所述核心场景关联的聚集组件有利使用，则从所述聚集组件展现所述特定的分解类型。

29.如权利要求15所述的方法，其特征在于，所述衍生包括：

生成一包括以相对高度抽象为目标的组件类型和以相对低度抽象为目标的组件类型的双层框架。

30.如权利要求29所述的方法，其特征在于，以相对高度抽象为目标的所述组件类型被定向到核心场景。

31.如权利要求29所述的方法，其特征在于，以相对低度抽象为目标的所述组件类型与以相对高度抽象为目标的所述组件类型相比，向开发者提供了相对更大数量的控制。

32.如权利要求15所述的方法，其特征在于，所述衍生包括：

衍生所述API以令开发者能够为所述核心场景实现一创建-设置-调用用法模式。

33.如权利要求32所述的方法，其特征在于，所述衍生包括：

用预选择的适合所述核心场景的参数产生所述API。

34.一种设计应用编程接口(API)的方法，其特征在于，它包括：

响应于对场景书写的至少一个代码样本，衍生用于所述场景的API；

使用多个开发者在所述API上执行一个或多个可用性学习；以及

基于所述一个或多个可用性学习修订所述API。

35.如权利要求34所述的方法，其特征在于，它还包括：

对所述场景书写多个代码样本，所述多个代码样本的每一相应的代码样本对应于多个编程语言的一相应的编程语言；

其中，所述衍生包括：

响应于所述多个代码样本，衍生用于所述场景的API。

36.如权利要求34所述的方法，其特征在于，它还包括，在所述API上执行一个或多个可用性学习之前：

由API设计者确定所衍生的API是否太过复杂；

如果所衍生的API被确定为太过复杂，则

由所述API设计者提炼所衍生的API以生成提炼的API；以及

由所述API设计者确定所提炼的API是否太过复杂。

37.如权利要求34所述的方法，其特征在于，它还包括：

断定所述多个开发者是否能在没有重大问题的情况下使用所述API；以及

当所述多个开发者不被断定为能够在没有重大问题的情况下使用所述API，则实现所述修订；

其中，所述修订包括：

38.如权利要求37所述的方法，其特征在于，它还包括：

对所述修订的API至少重复所述执行和所述断定。

39.如权利要求37所述的方法，其特征在于，所述断定包括：

对于至少一个目标开发者组的可用性的期望级别，断定所述多个开发者是否能在没有重大问题的情况下使用所述API，其中，所述可用性的期望级别包括对于以下的考虑：(i)由多个开发者对详细的API文档的频繁和/或广泛参考，(ii)所述多个开发者的大多数实现所述场景的失败，以及(iii)所述多个开发者是否采用与API设计者所期望的显著不同的方法。

40.如权利要求34所述的方法，其特征在于，它还包括：

为特征区域选择多个核心场景；

对所述多个核心场景的每一核心场景，重复所述衍生、所述执行和所述修订。

41.如权利要求40所述的方法，其特征在于，所述衍生包括：

对所述多个核心场景的每一核心场景生成一聚集组件。

42.如权利要求34所述的方法，其特征在于，所述衍生包括：

生成一与多个分解类型的每一相应的分解类型具有相应的关系的聚集组件。

43.如权利要求42所述的方法，其特征在于，所述生成包括：

生成所述聚集组件以支持为其书写所述至少一个代码样本的所述场景。

44.如权利要求42所述的方法，其特征在于，所述生成包括：

生成所述聚集组件以与所述多个分解类型中的至少一个分解类型有展现关系，并与所述多个分解类型中的至少一个其它分解类型有封装关系。

45.如权利要求44所述的方法，其特征在于，与所述聚集组件有封装关系的所述多个分解类型中的至少一个其它类型可由所述聚集组件传送，用于与另一组件类型的直接交互。

46.如权利要求42所述的方法，其特征在于，所述多个分解类型使用面向对象的技术来设计。

47.一种设计应用编程接口(API)的方法，其特征在于，所述方法包括：

为核心场景准备多个代码样本，所述多个代码样本的每一相应的代码样本对应于多个编程语言的一相应的编程语言；

响应于所述多个代码样本，衍生用于所述核心场景的API；

基于所述一个或多个可用性学习修订所述API。

48.一种设计应用编程接口(API)的方法，其特征在于，所述方法包括：

为场景书写至少一个代码样本；以及

响应于所述至少一个代码样本，衍生用于所述场景的API，所述API包括(i)一适用于方便所述场景的实现的聚集组件，以及(ii)为所述聚集组件提供基础功能的多个分解类型，所述API启用了从在较简单的情况下使用所述聚集组件到在愈加复杂的情况下使用所述多个分解类型的一个递增部分的逐步渐进。

49.一种设计应用编程接口(API)的方法，其特征在于，所述方法包括：

衍生至少一个聚集组件以支持用于至少一个场景的至少一个代码样本；

确定对所述至少一个场景的另外的需求；

判定所述另外的需求是否能在不向所述至少一个场景添加不适当的复杂度的情况下被添加到所述至少一个聚集组件中；以及

如果不能，则响应于所述判定，定义多个分解类型。

50.如权利要求49所述的方法，其特征在于，它还包括：

如果是，则提炼所述至少一个聚集组件以结合所述另外的需求。

51.如权利要求49所述的方法，其特征在于，它还包括：

为特征区域选择多个核心场景，所述多个核心场景包括至少一个场景；以及

为所述多个核心场景书写示出较佳的代码行的多个代码样本，所述多个代码样本包括所述至少一个代码样本；

其中，所述衍生包括：

衍生包括所述至少一个聚集组件的多个聚集组件，以支持用于所述多个核心场景的所述多个代码样本。

52.如权利要求49所述的方法，其特征在于，所述衍生包括：

用适当的方法、默认值和抽象衍生所述至少一个聚集组件，以支持用于所述至少一个场景的所述至少一个代码样本。

53.如权利要求49所述的方法，其特征在于，它还包括：

依照所述至少一个衍生的聚集组件提炼所述至少一个代码样本；以及

就简易性评估所提炼的至少一个代码样本；以及

如果在所述评估中所提炼的至少一个代码样本尚不足够简单，重复所述衍生。

54.如权利要求49所述的方法，其特征在于，所述确定包括：

确定对所述至少一个场景的另外的需求，其中，所述另外的需求包括另外的场景、另外的用法以及与其它组件类型的另外的交互。

55.如权利要求49所述的方法，其特征在于，所述判定包括：

考虑向所述至少一个聚集组件添加所述另外的需求是否阻碍了一创建-设置-调用用法模式。

56.如权利要求49所述的方法，其特征在于，所述定义包括：

响应于所述判定，用一组完整功能的理想分解定义所述多个分解类型。

57.如权利要求49所述的方法，其特征在于，所述定义包括：

响应于所述判定，使用一个或多个面向对象的方法定义所述多个分解类型。

58.如权利要求49所述的方法，其特征在于，它还包括：

确定所述至少一个聚集组件是否封装或展现所述多个分解类型的每一分解类型的功能。

59.如权利要求49所述的方法，其特征在于，它还包括：

提炼所述多个分解类型以支持所述至少一个聚集组件和所述另外的需求。