最佳实践：更好的设计你的 REST API
由于 REST 可以降低开发的复杂度，提高系统的可伸缩性，增强系统的可扩展性，简化应用系统之间的集成，因而得到了广大开发人员的喜爱，同时得到了业界广泛的支持。比如 IBM，Google 等公司的很多产品都提供了 REST API 给开发人员；与此同时，大量的开源项目和云计算服务都提供了 REST API 接口。而在最近，一些新产品的开发甚至已经几乎完全抛弃了传统的类似 JSP 的技术， 转而大量使用 REST 风格的构架设计， 即在服务器端所有商业逻辑都以 REST API 的方式暴露给客户端， 所有浏览器用户界面使用 widget，Ajax，HTML5 等技术，用 HTTP 的方式与后台直接交互。那么， 在 REST API 爆炸式增长的今天， 我们应该如何更好的设计我们的接口， 来提高我们的 API 的可用性，易用性，可维护性与可扩展性呢？本文将从以下方面与您探讨 REST API 设计方面的最佳实践：如何规划资源标识结构与 URI 模式如何根据应用场景提供内容协商如何正确的使用 HTTP 响应代码如何处理缓存和并发请求如何利用数据冗余和链接元素先决条件如果您具有如下知识与经验，将有助于您阅读和理解本文章的内容 。REST 相关的基本知识；HTTP 协议的基本知识；一定的 Web 开发经验。REST 简介REST 是英文 Representational State Transfer 的缩写，是近年来迅速兴起的，一种基于 HTTP，URI，以及 XML 这些现有协议与标准的，针对网络应用的设计和开发方式。它可以降低开发的复杂度，提高系统的可伸缩性。REST 的核心是可编辑的资源及其集合，用符合 Atom 文档标准的 Feed 和 Entry 表示。每个资源或者集合有一个惟一的 URI。系统以资源为中心，构建并提供一系列的 Web 服务。REST 的基本概念和原则包括：系统上的所有事物都被抽象为资源；每个资源对应唯一的资源标识；对资源的操作不会改变资源标识本身；所有的操作都是无状态的；等等。在 REST 中，开发人员显式地使用 HTTP 方法，对系统资源进行创建、读取、更新和删除的操作：使用 POST 方法在服务器上创建资源使用 GET 方法从服务器检索某个资源或者资源集合使用 PUT 方法对服务器的现有资源进行更新使用 DELETE 方法删除服务器的某个资源图 1. 用 HTTP 方法操作相册系统资源的简单范例更好的规划你的资源标识结构与 URI 模式REST 中，最基本的莫过于资源标识结构和 URI 模式了。更好的规划他们，是我们的 API 设计取得成功的最关键的一步。首先，我们来看看基本资源类型上文中提到，在 REST 构架的设计中，系统中的所有事物都被抽象为资源。在一个文档系统中，文档，目录，注释，草稿，等等，是组成系统的资源。在一个银行系统中，客户信息，理财产品，利率信息，网点信息，等等，是组成系统的资源。在一个航空客票系统中，旅客信息，机票订单，航班信息，机场信息，等等，是组成系统的资源。这些资源，通常在系统中以“Entry”的形式出现。下面的代码样例向您展示了一个常见的“Entry”资源。清单 1. 一个简单的 Entry 资源样例 REST API 请求：
GET /航班信息/CA827/entry
&id& CA827 &/id&
&link href="航班信息 /CA827/entry" rel="self"/&
&title type="text"&CA827 &/title&
&published&T02:35:40.937Z &/published&
&updated&T02:35:40.937Z &/updated&
&ca:from&Beijing &/ca:from&
&ca:to&Changsha &/ca:to&
&ca:time&09:30:00 &/ca:time&
&ca:aircraft&AB330 &/ca:aircraft&
&summary type="text"/&
&/entry&我们会注意到，这些资源，在描述了某种事物的同时，还有可能存在一定的层次结构关系。比如，文档从属于某个目录，注释从属于文档；旅客信息可以从属于机票订单，也可以从属于某个航班。当我们的资源有这种层次关系的时候，我们不妨在 URI 模式的设计中，用复合的 URI 来帮助开发者更好的理解和设计资源。比如， 针对一个文档的评论， 他的 URI 模式可以设计成如下：/ 文件夹 / [ 文件夹名 ] / 文件 / [ 文件名 ] / 评论 / [ 评论唯一标示 ]。 这样，在构造和解析 URI 的过程中， 可以帮助开发者更好的理解系统，设计程序。其次，我们来看看集合资源类型资源，除了作为独立个体可以被访问，还可以由多个个体组合成一个集合，在系统中，通常以“feed”的形式存在。资源的集合， 可以是处于相同层次上，有相同从属关系的一组资源，比如一个文件夹下的所有文件； 也可以是根据某种条件查询出来的查询结果的资源集合，比如所有 30 岁以上 40 岁以下，拥有 100 万资产以上客户的名单。下面，我们来讨论一下设计集合类型资源的 REST API 时需要考虑的问题。使用过滤条件来帮助用户更准确地获取数据我们要返回的资源集合，无论是否有相同从属关系，大部分时候都需要进行必要的过滤，提供足够的过滤参数，查询参数， 能够帮助开发者高效的，准确地获取所需要的数据。 在服务器端过滤数据通常比客户端高效，并且减少了不必要的数据传输，可以大大减少网络开销，提高执行效率。最常见的过滤条件，是通过 URL 参数实现，比如 / 环境工程系 / 学生 ? 籍贯 = 北京 & 性别 = 女。很多时候，我们需要制定更加复杂的过滤条件，那么我们可以有两种选择：首先，我们可以使用正则表达式或者服务器可以理解的语法， 比如 / 环境工程系 / 学生 ?filter=age between (15, 18)其次，我们还可以使用 POST 方法，携带一个文件来描述复杂的查询条件，文件的格式与语法通常需要在服务器端有相应的设计与定义。不过通常 POST 方法没有缓存机制，因此不是查询数据的首选。使用排序来帮助客户端更好的展现数据虽然进行客户端排序对于开发者来说是件轻而易举的事情，但是直接得到已经排序的返回结果，仍然是大部分开发者所期望的。尤其是很多时候，我们在浏览器，使用 Widget 展示结果，不适宜在客户端存储大量数据进行内存排序。排序， 通常有 2 个参数， 一个是用来排序的字段， 一个是排序的升序降续方式。比如我们可以用支持这样的参数组合的手段，提供基本的排序能力：?sortOrder=asc&sortField=age使用分页来帮助客户端处理大量数据由于返回的结果可能有几百几千条记录，将这些记录一次性的返回给客户端是不现实的，巨大的网络流量开销和客户端数据区的内存开销，都是我们在应用开发的时候不希望看到的，因此，如果你的集合资源有可能有大量的数据返回，请务必提供分页的功能支持。我们通常用一个以上参数来制定一个返回结果的区域，比较常见的有下面两种：一种常见于用固定行数的表格来展示数据，用当前处于第几页和每页返回多少行数据来确定需要的数据， 比如 / 所有学生 ?page=5&pagesize=50另外一种常见于用更加灵活的界面展示数据，用从第几行开始，一共返回多少行数据来确定需要的数据， 比如 / 所有学生 ?startIndex=27&count=22下面是一个来自 IBM developerWorks 的 API 样例，尝试请求该 API，你可以看到该集合很好的支持了结果的分页与排序。同时我们从返回的信息中可以看到，每个文档 Entry 的 URI 都按照 / 社区库 /[ 社区库 ID]/ 文档 /[ 文档 ID] 的复合 URI 的模式设计的。清单 2. IBM developerWorks 的某个社区文件库的集合资源的 API REST API 请求：
/developerworks/mydeveloperworks
/files/form/anonymous/api/communitylibrary
/0a7c97bb-6cf9-4ddb-a918-d/feed?
pageSize=5&page=1&sK=modified&sO=dsc最后，我们来讨论一些特殊资源类型理想的 REST 世界，一切事物都抽象为资源，一切操作都抽象为增删改查。然而，所有事物与操作都可以很容易的按照这个规则作抽象吗？让我们看看这个例子：检入和检出一个文档 ---- 这个时候，我们要处理的资源是一个文档，然而增删改查似乎都无法与“检入检出”这个动作进行对应。当然，我们可以在文档资源中，设计一个检入检出状态的元素，通过编辑文档资源来实现。但是，这种设计从自然语义上看，并不是很贴切；并且增加了资源编辑操作的复杂度。如果我们来定义一个新的集合 ----“我检出的文档”，用创建一个集合资源来对应检出（创建一个文档锁），用删除一个集合资源来对应检入（删除一个文档锁）， 是不是逻辑上可以变得更加清楚？在 REST 这个以名词为核心的构架结构中，当你遇到一些动词特性比较强的操作，而又很难用原始资源的增删改查来匹配的时候，不妨换个思路， 通过引入新的逻辑资源集合的方式， 来进行 API 的设计与规划。理解和使用内容协商我们的开发者在发送一个 REST API 请求的同时，根据应用场景，针对相同的资源，可能会期待不同的返回形式。比如，我希望根据用户客户端语言，同一个资源的内容可以返回不同的语言。又比如，当我使用 Java 编程的时候，我希望得到 ATOM 格式的返回结果，而当我使用 JavaScript 编程的时候，我希望得到 Json 格式的返回结果。因此，我们在设计 REST API 的时候，应该提供完备的内容协商能力。使用 URL 参数进行内容协商最容易想到的自然是通过 URL 参数进行控制，我们经常看到形如 / 航班号 /entry? format=JSON 这样的 URL。这种方式的优势就是简单灵活， 你可以通过任何 URL 参数来组合你的输出格式。下面是一个来自 IBM developerWorks 的 API 样例，尝试请求该 API，你可以看到该集合是如何支持不同的输出格式请求的。清单 3. IBM developerWorks 的文件服务标签云的 API REST API 请求，要求返回 XML 格式数据：
/developerworks/mydeveloperworks
/files/form/anonymous/api/tags/feed?format=xml
&scope=document&pageSize=30&sK=cloud&sO=dsc
REST API 请求，要求返回 JSON 格式数据：
/developerworks/mydeveloperworks
/files/form/anonymous/api/tags/feed?format=json
&scope=document&pageSize=30&sK=cloud&sO=dsc使用 Accept 头进行内容协商使用 URL 参数，简单灵活，但是也由此带来了设计上的随意和不标准。并且，过多的参数会导致 URL 的可读性变差，更有甚者，可能会导致 URL 过长，超出规范，API 请求无法执行。更为标准的内容协商方式是使用 HTTP 头。我们通常使用 Accept 来设置我们接受的返回结果的内容格式，用 Accept-Charset 来设置字符集，用 Accept-Encoding 来设置数据传输格式，用 Accept-Language 来设置语言。使用 URI 模式进行内容协商还有一种模式，就是将协商设置直接作为 URI 的一部分，将不同的返回视为不同的资源，比如 / 航班号 /json 来返回 JSON 格式的结果，用 / 航班号 /atom 来返回 ATOM 格式的结果。正确的使用 HTTP 响应代码作为 API 的设计者，正确的将 API 执行结果和失败原因用清晰简洁的方式传达给客户程序是十分关键的一步。 我们确实可以在 HTTP 的相应内容中描述是否成功，如果出错是因为什么， 然而， 这就意味着用户需要进行内容解析，才知道执行结果和错误原因。因此，HTTP 响应代码可以保证客户端在第一时间用最高效的方式获知 API 运行结果，并采取相应动作。 下表列出了比较常用的响应代码。表 1. 常用 HTTP 响应代码含义HTTP 响应代码代码含义
已创建，请求成功且服务器已创建了新的资源。
是否只显示处于警告状态的应用实例
重定向 , 请求的网页已被永久移动到新位置。服务器返回此响应时，会自动将请求者转到新位置。
重定向 , 请求的网页临时移动到新位置，但求者应继续使用原有位置来进行以后的请求。302 会自动将请求者转到不同的临时位置。
未修改，自从上次请求后，请求的网页未被修改过。服务器返回此响应时，不会返回网页内容。
错误请求 , 服务器不理解请求的语法。
未授权 , 请求要求进行身份验证。
已禁止 , 服务器拒绝请求。
未找到 , 服务器找不到请求的网页。
方法禁用 , 禁用请求中所指定的方法。
不接受 , 无法使用请求的内容特性来响应请求的网页。
请求超时 , 服务器等候请求时超时。
已删除 , 如果请求的资源已被永久删除，那么，服务器会返回此响应。
未满足前提条件 , 服务器未满足请求者在请求中设置的其中一个前提条件。
不支持的媒体类型 , 请求的格式不受请求页面的支持。
内部服务器错误。
使用 HTTP 头处理缓存和并发缓存和并发处理，从来是大型软件系统设计中的重要组成部分。使用 HTTP 头进行缓存处理在 REST 的构架中，我们除了在与后台的数据交换中，需要有一个良好的缓存机制外，针对 REST API 请求都是在远端用 HTTP 发起这一特点，还需要为网络缓存进行更多考虑。通过减少 HTTP 响应内容，避免不必要的 HTTP 连接等方式，达到提高 REST API 使用效率的目的。HTTP 头中，有多个字段可以用于缓存处理。比较常用的有缓存控制和条件请求。缓存控制：缓存控制通常是需要客户端，缓存服务器 / 代理服务器与业务服务器一起发生作用。HTTP 头中有“Cache-control”字段来控制如何使用缓存，常见的取值有 private、no-cache、max-age、must-revalidate 等。比如当你给返回的数据内容设置 max-age=600，那么当用户隔了 30 秒再次请求的时候，就不会导致重新请求后台数据。另外，也可以通过“Expires”字段来指定内容过期时间，在此时间前的请求都不会导致后台程序重新请求数据。下图展示了 max-age 是如何工作的。图 2. 缓存控制工作方式的简单范例条件请求与电子标签：很多时候，数据内容可能会几个小时甚至几天都不会发生变动，这个时候根据请求时间间隔来控制缓存，就不能满足系统的需求了。通过支持条件请求与电子标签，可以帮助我们来解决这个问题。当用户请求数据内容时，系统在返回数据的同时，在 HTTP 头中，将返回根据服务器内容的最后修改时间 Last-Modified，或者根据服务器内容生成电子标签 ETag。 当用户再次请求数据时，就可以在 HTTP 请求中使用 If-Modified-Since 或者 If-None-Match 头信息，把上次请求得到的时间戳或者电子标签传给服务器。当收到一个有条件请求的 HTTP 头的 REST 请求的时候，我们的程序需要将收到的时间戳或者电子标签与当前内容作比较，就可以很容易的知道用户请求的数据内容在这段时间是否发生过修改，并根据比较结果返回给用户最新内容，或者用 HTTP 响应码 304 告知用户，内容没有变化。下面是一个来自 IBM developerWorks 的 API 样例，尝试请求该 API，你可以看到该 API 会在 HTTP 头中返回电子标签和缓存处理信息。清单 4. IBM developerWorks 的带有电子标签的文件服务 API REST API 请求：
/developerworks/mydeveloperworks
/form/anonymous/api/communitylibrary
/7e2e8015-bf72-43b6-bacd-36565b67febc/document
/ddc0ef4e-224e-449c-bb2c-f919fafb17d2
/entry?acls=true&includeRecommendation=true
&includeTags=false&includeLibraryInfo=true&format=xml使用 HTTP 头进行并发处理上文我们提到了使用条件请求控制缓存，其实我们还可以使用条件请求进行并发处理。比如当用户 Alice 和 Bob 通过 REST 获取了一篇文档。Bob 阅读文档之后，通过 PUT 来修改文档；而此前几分钟，Alice 刚刚修改了这篇文档，于是 Bob 就在毫不知情的情况下不慎覆盖了 Alice 的修改。通过在写操作中支持条件请求，我们可以更好的处理并发修改。用户在发出修改请求的同时，在 HTTP 请求中使用 If-Not-Modified-Since 或者 If-Match 头信息，把获取数据时得到的时间戳或者电子标签传给服务器；我们的程序通过与服务器当前内容的比较，就可以知道，这个修改请求是否是针对当前内容提出的。当服务器发现内容已经被其他用户修改过了，就不会执行修改请求，并返回 HTTP 响应码 412（未满足前提条件）给用户。下图展示了使用条件请求和电子标签进行并发处理是如何工作的图 3. 支持条件请求时的并发处理简单范例更好的使用数据冗余和链接元素在 ATOM 文档中，我们用各种数据元素来传递信息。其中有一类元素叫做链接，可以用于开发者的进一步访问。通常，我们会提供编辑当前资源的链接，访问当前资源的链接，等等。通过更加灵活的使用这类链接元素，以及提供必要的数据冗余，我们可以大大简化开发者的编程逻辑，提高 REST API 的使用效率 。首先，让我们来看看数据冗余的例子：我们在一个航班信息的文档中，通常会包括飞机的型号；而我们可能经常需要在显示航班信息的时候，同时显示更多的飞机信息（如单通道还是双通道，载客人数等）。这个时候，我们就需要对飞机型号的资源再发起一次请求，才能获得我们需要的信息。如果我们可以在请求航班信息的时候，返回飞机型号的同时获得更多的该型号的信息，就可以减少一次网络连接。为了保证 API 的灵活与效率，我们可以提供一个开关参数，如 includeAircraftDetail=true。其次，让我们来看看链接元素的例子：我们要展示一个文件夹下面所有的文件，并允许用户察看每个文件都允许哪些人编辑，哪些人下载以及将某文件放入收藏夹。这时候，我们可以考虑将这些可以执行的操作的 API 都用链接元素的方式返回给客户端，这样，开发者无需自己拼接 API 调用的 URL，就可以使用，从而降低代码复杂度。清单 5. 一个简单的使用链接元素的样例 REST API 请求：
GET /doc/docID12345/entry
&id& docID12345&/id&
&link href="doc/docID12345/entry" rel="self"/&
&title type="text"&Doc Title &/title&
&published&T02:35:40.937Z &/published&
&updated&T02:35:40.937Z &/updated&
&atom:link doc:rel="reader"
href="/doc/docID12345/reader/feed"
rel="related" type="application/atom+xml"/&
&atom:link doc:rel="editor"
href="/doc/docID12345/editor/feed"
rel="related" type="application/atom+xml"/&
&atom:link ca:rel="collect"
href="/doc/collect?Add=docID12345"
rel="related" type="application/atom+xml"/&&/entry&更多的需要注意的细节与技巧除了以上提到的方面，还有大量的细节与技巧，可以帮助我们更好的设计 REST API：批量更新：当用户需要更新多个资源的时候，你打算让开发者一次次的发送 HTTP 请求逐个更新吗？你可以考虑在设计 API 的时候允许客户同时创建或者更新多个资源。REST 安全：除了使用固有的 HTTP 基本验证，你还可以考虑通过支持表单验证，LTPA 验证，Open ID 验证等方式，来满足更多的企业安全要求。文档服务：是否由于 API 持续更新，使得客户端连接不同版本服务的时候疲于奔命？尝试着把你的 API 定义规范成 XML 文档，这样客户端很容易理解当前服务可以提供哪些功能，以及如何使用这些功能。你还可以通过阅读其他文档得到更多这方面的指导，本文无法将所有的细节与技巧一一穷尽。总结通过以上的经验介绍和技巧举例，我们学习到了如何应用最佳实践来更好的设计 REST API。我们注意到，由于 REST API 主要针对网络应用， 并且大量调用来自于浏览器脚本，因此在细节上有很多自己独特的需要注意的技巧。此外，由于 REST 越来越成为一种系统设计的原则与构架，也要求我们的程序开发人员在设计 API 的时候需要用构架师的视角与高度来思考。希望本文能够帮助您打开 REST API 设计的思路，摸索和总结出更多的技巧，与广大开发人员分享。
阅读 RFC 文档，以了解 HTTP 1.1 标准：
阅读 RFC 文档，以了解 URI 标准：
阅读 HTTP 响应状态码相关文档，以了解标准的状态码，包括可以执行的后续方法以及响应需要的信息：
阅读 developerWorks 文章：认识 Atom 发布协议 -- 使用 Atom 发布协议创建和编辑 Web 资源， 以学习 ATOM 协议的基本知识：
阅读 developerWorks 文章 : 基于 REST 的 Web 服务，以学习 REST 的基础知识：
阅读 developerWorks 文章 : 编写 REST 服务 -- 使用 Java 技术和 Atom 发布协议创建 REST 服务 , 以学习如何开发 REST 服务：
访问 developerWorks 专栏 : REST 与 Web 开发 ，以学习更多 REST 开发的知识：
访问，以获得更多关于如何开发 Web 服务应用程序的文章以及入门级、中级和高级教程
：通过专门关于 Web 技术的文章和教程，扩展您在网站开发方面的技能。：这是有关 Ajax 编程模型信息的一站式中心，包括很多文档、教程、论坛、blog、wiki 和新闻。任何 Ajax 的新信息都能在这里找到。，这是有关 Web 2.0 相关信息的一站式中心，包括大量 Web 2.0 技术文章、教程、下载和相关技术资源。您还可以通过
栏目，迅速了解 Web 2.0 的相关概念。
添加或订阅评论，请先或。
有新评论时提醒我
static.content.url=/developerworks/js/artrating/SITE_ID=10Zone=Web developmentArticleID=631858ArticleTitle=最佳实践：更好的设计你的 REST APIpublish-date=苹果Xcode帮助文档阅读指南
｜ 更新于 7月前
等7人欣赏。
一直想写这么一个东西，长期以来我发现很多初学者的问题在于不掌握学习的方法，所以，Xcode那么好的SDK文档摆在那里，对他们也起不到什么太大的作用。从论坛、微博等等地方看到的初学者提出的问题，也暴露出他们不知道很多他们的疑惑其实在文档里面写的非常清楚。而有时候。或者有些人意识到了，。
中国的技术社区有一个很没意思的毛病，就是技术深了，看不懂骂不知所云，技术浅了，看得懂骂没有技术含量。不过管那么孙子做啥，对于现在可能还不知道怎么阅读文档的人，希望这篇文章有所教益吧。
Xcode文档的结构
如上图，打开后，整个文档界面有左面的侧栏和右面的内容区域构成。左面的侧栏可以选择不同的文档库。你的Xcode里面一般来说有一组不同版本的iOS文档库、一组不同版本的OS X文档库，以及一个Xcode文档库。
如果你这里没有你要查看的文档库，你可以选择Xcode的Preferences菜单，然后选择Downloads -> Documentation。在这里可以看到已经下载安装了的文档库，还没有下载的文档库，可以酌情选择。如下图：
然后我们看，文档内容区域的左侧导航区域，这里揭示了文档库的结构。如下图：
首先是，Resource Types，也就是资源类型。文档库里面全部的文档都是这几个类型中的一个：
Getting Started —— 新手入门，一般来说，是给完全的新手看的。建议初学者看看，这里面有一些建立观念的东西，有了这些建立观念的东西，后面的学习就比较容易了。
Guides —— 指南，指南是Xcode里面最酷最好的部分，学会看指南则大多数情况完全不用买书。Xcode文档里面的指南，就是一个一个问题的，从一个问题，或者系统的一个方面出发，一步一步详细介绍怎么使用Cocoa库的文档。一般程序员比较熟悉的是Reference，就是你查某个类、方法、函数的文档时候，冒出来的东西。那些其实是一点一点的细碎知识，光看那些东西就完全没有脉络。而Guides就是帮你整理好的学习的脉络。
Reference —— 参考资料。一个一个框架一个一个类组织起来的文档，包含了每个方法的使用方法。
Release Notes —— 发布说明。一个iOS新版本带来了哪些新特性，这样的信息，熟悉新iOS，比较不同iOS版本API不同，都需要参考这些文档。
Sample Code —— 示例代码。苹果官方提供的一些示例代码，帮助你学习某些技术某些API。非常强烈建议学习的时候参考，一方面光看文档有时候还是很难弄明白具体实现是怎么回事儿。另外一方面这些示例代码都是苹果的工程师写的，你从示例代码的变迁可以看到苹果官方推荐的代码风格流变。
Technical Notes —— 技术说明。一些技术主题文章，有空的时候可以浏览一下。往往会有一些收获。
Technical Q&A —— 常见技术问答。这是技术社区里面一些常见问题以及回答的整理。
Video —— 视频。目前主要是WWDC的视频，实际上是登录到开发者网站上去浏览的，这里就是快捷方式。想深入学习的话，一定不能错过，大量的看，不仅可以学好技术，还可以练好英文。
总结一下，这里面的Reference、Release Notes、Sample Code、Technical Notes、Technical Q&A，一般来说只是备查的。主要要看的是Getting Started和Guides。
然后下面是Topics，也就是话题，被分为：
Audio & Video —— 音视频
Languages & Utilities —— 语言和工具，Objective-C的一些知识，App Store的管理工具等。
Mathematical Computation —— 数学计算。
Data Management —— 数据管理。
General —— 一般性的问题。
Graphics & Animation —— 图形和动画。
Networking & Internet —— 网络问题。
Performance —— 性能。
Security —— 安全。
User Experience —— 用户体验。
这里不多说，大多数都是顾名思义的问题。但是值得一提的就是有很多初学者说，我想好好了解下图形和动画的技术，但是文档里面找不到，这就只能说，你睁着大大的眼睛，为毛左看右看看不到呢？
最下面是Frameworks（框架），分为：
Cocoa Touch Layer
Media Layer
Core Services Layer
Core OS Layer
这里我们先不讨论这个东西，后面会仔细讲。
总体来说左边的导航区域就是用三种不同的维度，来帮你精准定位你需要的内容。
现在我们看内容区域的右边。注意上面的文档过滤器。如下图：
假设，你现在想看关于性能方面的Guides，那么你应该做的就是在左面的导航，点击Topics -> Performance，然后在右边的文档过滤器上面输入Guides。或者你也可以在左边的导航，点击 Resource Types -> Guides，然后在文档过滤器里面输入 Performance。
熟练使用导航和文档过滤器的话，学习就会非常方便快捷。
共159条回复
｜ 更新于 7月前
前面我们讲Xcode的文档结构是在介绍如何能够快速定位到你要找的内容。但是很多人的问题可能是一开始就根本不知道要读什么。
这里我们就介绍自学iOS开发应该遵循或者说我们推荐的必读文档的阅读顺序。
阅读顺序：
《马上着手开发 iOS 应用程序 (Start Developing iOS Apps Today)》
《Your First iOS App》
《Your Second iOS App: Storyboards》
《Your Third iOS App: iCloud》
《iOS Technology Overview》
《iOS Human Interface Guidelines》
《Learning Objective-C: A Primer》和《Programming with Objective-C》
《iOS App Programming Guide》
《View Programming Guide for iOS》和《View Controller Programming Guide for iOS》
《Table View Programming Guide for iOS》
首先应该看的是Getting Started里面的《马上着手开发 iOS 应用程序 (Start Developing iOS Apps Today)》（中英文版本皆有，苹果官方的翻译）。这个文档讲的很浅，但是是建立概念的文档，你以后在开发里面经常遇到的概念，在这里都有包含，特别注意是，这个文档看起来简单，但是每页下面的相关文章，不是选读，都是必读。
即使是很多做了iOS开发很久的同学，其实也有很多概念上的误解，现代程序开发越来越简单，工具越来越强大，往往有些误解也可以继续前行，但是实际上不建立扎实的基础是很吃亏的，往往后面理解和解决一个不难解决小问题都要付出很多辛苦。
阅读这个文档的目的和检测标准是，以后你看到iOS开发中的基本概念，都大致所有了解。
读完《马上着手开发 iOS 应用程序 (Start Developing iOS Apps Today)》后，应该去看Your XXX iOS App系列这个系列不是什么很难的文章，你也不必着急先去学习Objective-C，学什么C语言就更不要着急。我推荐的学习方法是有成就的逐步学习法。在学习系统体系架构、Objective-C之前，你可以先按照文档写一个全天下最简单的App，完成学习过程中第一个里程碑。在这个过程中不用担心有什么疑问，有什么不懂，先照着做就是。
阅读这三个文档的目的和检测标准是，把这三个Demo App做出来在模拟器上跑起来。
在这个过程中，你对开发工具的基本认识就建立起来了，也有了成就感，去了魅（就是消除了对iOS开发的神秘感）。
再往下，建议你去看《iOS Technology Overview》（iOS技术概览），iOS不是一个技术，而是一堆技术，前一篇讲到文档导航区域的分类，框架分类的时候，我说不细讲的原因就在于此，你要做一个动画应该用Core Animation还是OpenGL？你要做一些文本相关操作应该用Core Text还是什么，就是看这里。
学习现代的程序开发，语言和框架并重。我们Tiny4Cocoa叫做这个名字的原因就是，iOS/Mac开发者的代表往往就是这个Cocoa框架，就是这个SDK。大多数你所需要的功能都躺在框架里面，你知道框架的结构，你才知道怎么去寻找相关的技术资料。
阅读这个文档的目的和检测标准是，遇到具体问题，知道应该去看哪方面的文档。
再下来，建议阅读的是《iOS Human Interface Guidelines》，Mac/iOS平台虽然也是百花齐放各类程序、App都有，但是总体看来，大多数优秀App的UI看起来都和整个系统很协调。这和Windows以及很多其他平台完全不同。这是为什么呢？
很大程度就归功于《Human Interface Guidelines》文化，所谓Human Interface Guidelines就是用户界面的规范，在苹果它还专门有一个缩写叫做HIG，是天条一样的东西。所有的App都推荐遵循HIG，遵循了HIG，你做的东西用户看起来就会觉得和整个系统很协调。即使是你要做一些创新的设计，你势必会打破HIG的限制，但是你这个时候仍旧应该遵循HIG的精神。
此外，你阅读HIG的很重要一点是了解整个UI结构和UE行为的逻辑机理，这样才能在你设计界面的时候有所依据。
阅读这个文档的目的和检测标准是，看到任何一个App，你可以知道它的任何一个UI是系统控件，还是自定义控件，它的层次关系等等。
《Learning Objective-C: A Primer》是非常初级和简单的入门，适合先阅读。《Programming with Objective-C》超微复杂一点点，适合后阅读。
一般人建议先学习语言，我反之建议先做了一个App，然后再学习语言。原因有几个，首先现代开发工具，往往不是用来开发控制台程序的，上来就会有框架，光懂语言不会使用IDE，甚至可能会更麻烦。再其次就是，其实现代语言发展到了面向对象以后，库往往比语言更复杂，更重要，或者说更多的时候，我们是在学习库，而不是语言，语言只是库的一个载体。
比如，Delegate和Block等等都和Cocoa的UI异步机制关系紧密，光看代码，这些语言元素非常难以学习，也完全不知道其意义在哪里。
阅读这个文档的目的和检测标准是，看得懂基本的Objective-C代码，方便后面的学习和阅读各种示例代码。
《iOS App Programming Guide》基本上介绍的就是开发一个App的完整流程，包括App的生命周期、休眠、激活等等，里面介绍的细节颇多。正式开发第一个上线的App之前必看。或者开发了一个App，临到提交前必看才文档。
阅读这个文档的目的和检测标准是，了解全部流程和很多细节问题。
《View Programming Guide for iOS》和《View Controller Programming Guide for iOS》非常重要。View是整个图形界面里面最重要的概念。所有的图形、界面绘制都基于View。你看到的一切复杂的用户界面，就是各种不同的View的组合堆叠。
View Controller是View和某种逻辑在一起的组合，本质上这种组合不是必须的，但是是大大降低编程复杂度的一种设计。很多人不懂什么是View什么是View Controller，这样写起代码来就很痛苦。
阅读这个文档的目的和检测标准是，深刻理解什么是View，什么是View Controller，理解什么情况用View，什么情况用View Controller。
UITableView是最重要的一个控件，是最常用的UI界面元素。在UICollectionView出现之前，大量的内容列表展示的自定义控件都是基于UITableView，比如很多书架、图片Grid其实都是UITableView做的。
所以《Table View Programming Guide for iOS》非常重要，一定要好好阅读。
阅读这个文档的目的和检测标准是，深刻理解UITableView／UITableViewController的理论和使用方法。
我推荐的必读文档就这么多，仔细看的话，最多也就是今天就看完了。学习一个东西，如果有一点点耐心，有正确的方法其实不难，不是说脑子非要很聪明，大多数人都可以做到一个星期就学会iOS开发，其实就是读完这些文档，大多数人就会了。
就像我强调了无数次，阅读英文文档不难，我自己从当年看英文文档非常吃力，必须查词典开始，认真的看英文文档，不会就查词典，一个多月过去，读英文文档就完全不需要查词典了。
我们公司主程 @ 老师，也说他原来英语也很不好，甚至现在英语仍旧很烂，但是看英文文档完全没有问题，也就是几个星期的认真学习以后就突破了。
其实学习iOS也如此。当然我不是说你看懂这10组文档就再也不用看别的了。而是说，如果你看懂了这10组文档，你就从初学者，或者是虽然会写一些程序，但是对iOS其实还不懂的状态，变成了一个入门者。
我不希望这个文章可以一句一句的帮你学会iOS是什么，这个文章的目的是帮你快速入门。一旦你入门了，你再遇到问题该看什么，你就不需要我讲了，你自己就知道了。一旦入门了，你就会发现，Xcode里面别的文档讲的内容虽然不同，但是结构你已经很清楚了，你学习起来很方便。
阅读本文的目的和检测标准是，遇到问题，知道看什么文档，想提升自己技术的时候，知道按照什么脉络自己组织阅读。
｜ 更新于 7月前
如何查询文档
Quick Help
最快捷的查询帮助文档的方法是不需要键入任何关键词的。你只需要在Xcode代码编辑器里，按住Option键，然后点击你想查询的关键词，就会获得关键词的帮助信息。如下图：
帮助信息会包括，一些简单的描述、哪个iOS操作系统开始提供，头文件，参考文档。头文件和参考文档是可以直接点击的。
即使你点击的关键字不是Cocoa库的内容，是自己代码里面的类或者方法，也可以获得相关的定义信息。如下图：
与之相关的热键是Command键加鼠标点击，即可跳到任何一个类名或者方法名的所定义的头文件。
快速查询帮助的另外一个方法是直接打开Quick Help栏，如下图，首先找到“右侧栏开关”，然后找到“Quick Help”开关即可打开。
Quick Help栏的作用机制是，只要它在打开状态，只要输入光标在什么关键字上，Quick Help栏就会显示跟关键字相关的简要帮助信息，跟Option键加点击的信息基本一致，但可能略微丰富一点。
写代码的时候，在大多数情况下，查询下快速帮助，看看头文件，就足以了。
文档阅读界面最左面的上端的放大镜按钮就是搜索界面。下图是我们搜索uiimage，得到的搜索结果。
首先值得注意的是，结果也是分类的，分为Reference、System Guides、Tools Guides、Sample Code这四类。类别很利于我们快速找到我们需要的信息。前面已经介绍过类别，跟那个基本一致，参照即可。
另外需要注意的是，搜索框下面的选项，首先是Hits Must(什么样的结果才会命中)，包含了三项：
contain search term 这是最常见的就是结果包含搜索词
start with search term 由搜索词开始
match search term 必须完全匹配搜索词
然后是Languages（语言选项），包含Javascript、C++、Java、Objective-C、C语言。
然后是，Find in（在哪些文档库搜索），包含了你Xcode里面安装的全部文档库。
最后，我们简单介绍下怎么阅读文档。文档的阅读界面如下图：
值得注意的是，标题下面这几样：
Inherits from
继承关系，继承自
Conforms to 遵循什么协议
Framework 属于什么框架
Availability 从什么iOS版本开始支持
Declared in 头文件
Related sample code 相关例子代码
Companion guide 相关的指南（UIImage没有，很多其他的类有）
在其次一个很重要的东西，其实是标题上面那一条窄窄的导航栏，那是一个多层树状导航栏，看文档的时候，可以点击那个栏的不同位置浏览。
其实这个栏包含了整个文档库的组织结构树状图，可惜只有在这个界面才能浏览。有兴趣的可以慢慢浏览，里面信息量其实非常大。
前排广告招租。
这个帖子太好了：）期待更新啊：）
对你的感谢真想用星爷的一句话来表达。......
对于真正要入学iOS者，真的非常有用，因为她的学习跟其他的学习真的太不相同了。本身的reference太丰富，太好了！很多人都不知道学习的方法。
期待。。。。。
现在流行的语言或者技术，其提供的文章是最好的学习资料。
其实，有自学能力的同学就应该好好吃提供的文档，其他的书籍资料倒不是非常推荐！
Xcode里的文档还是相当齐全的，很多人懒得看大概主要是因为英文吧。
这个真的很帮忙！
这个整理对于想进一步写好IOS的人来说真的很有帮助啊。
本帖有159个回复，因为您没有注册或者登录本站，所以，只能看到本帖的10条回复。如果想看到全部回复，请注册或者登录本站。}