概述

OCFWeb是用Objective-C编写的网络应用程序框架。您可以使用OCFWeb仅用几行代码来创建网络应用程序。虽然OCFWeb是Objective-Cloud.com开发和使用的，但它不依赖于Objective-Cloud.com。您可以在自己的服务器上使用OCFWeb（尽管我们希望您使用Objective-Cloud.com :））以及/或在您自己的OS X/iOS应用程序中使用它。实际上，OCFWeb是为了嵌入到用Objective-C编写的现有应用程序中而设计的。Sinatra（一个用Ruby编写的网络应用程序框架/DSL）启发了OCFWeb的开发。

示例：Hello World

以下代码片段显示了如何创建一个响应到对/的GET请求的网络应用程序。

@interface AppDelegate ()
@property (nonatomic, strong) OCFWebApplication *app;
@end

@implementation AppDelegate 

- (void)applicationDidFinishLaunching:(NSNotification *)n {
  // Create a instance of OCFWebApplication
  self.app = [OCFWebApplication new];

  // Add a handler for GET requests
  self.app[@"GET"][@"/"]  = ^(OCFRequest *request) {
    // request contains a lot of properties which describe the incoming request.

    // Respond to the request:
    request.respondWith(@"Hello World");
  };

  // Run your app on port 8080
  [self.app runOnPort:8080];
}
@end

在浏览器中打开http://127.0.0.1:8080/应该会显示一个包含“Hello World”字样的网站。不错吧？现在让我们更详细地看看这段代码

• 首先，您使用+new类方法创建OCFWebApplication的一个实例。这样会为您创建一个不执行任何有用操作的空白网络应用程序。
• 现在，您可以为OCFWebApplication的实例添加请求处理器。每个处理器由三部分组成（HTTP方法、路径、处理器代码块）。示例中添加处理器的各个部分如下
  1. HTTP方法：在第一个方括号[@"GET"]中指定了方法（"GET"）。这会将您的处理器与GET-HTTP请求相关联，与其他请求无关。
  2. 路径：在第二个方括号[@"/"]中指定了路径（"/"）。这会将您的处理器与对http://127.0.0.1/（尾部没有其他字符）发出的HTTP请求相关联。
  3. 处理器代码块：处理器代码块跟在“=”之后，是一个简单的C代码块，其原型如下：void^(OCFRequest *request)（没有返回类型，只有一个参数，即请求对象）。
• 一旦添加了处理器，网络应用程序就会通过发送+runOnPort:启动。这将自动在localhost上创建一个HTTP服务器。实现细节：使用的HTTP服务器名为OCFWebServer。基本上，OCFWebApplication只是OCFWebServer的漂亮包装。

以下是一些注意事项：一旦调用+runOnPort:，即将进入的请求将被OCFWebApplication检查。如果它找到了匹配请求的HTTP方法和路径的处理程序，您的处理程序块就会被调用。OCFWebApplication会将实际请求传递给您的处理程序块。接下来就是您的任务了：您必须创建一个响应。这可以同步或异步完成。无论您如何创建响应，一旦您有了它，您应该让OCFWebApplication知道您的响应，以便将其传递给客户端。在上述示例中，响应只是@"Hello World"。请求对象有一个名为respondWith的属性。respondWith是一个接受单个参数（类型为id）的块。您执行该块并将响应传递给它。此时，OCFWebApplication就知道您的响应了，并将其传递给客户端。

入门指南

OCFWeb使用CocoaPods。您可以通过运行以下命令安装CocoaPods

$ [sudo] gem install cocoapods
$ pod setup

然后从GitHub克隆或下载OCFWeb，并通过cd进入OCFWeb目录。该目录包含一个名为Podfile的文件。现在执行以下命令

$ pod install

这将下载所有依赖项。现在打开OCFWeb工作区，并选择方案“OCFWeb Mac Example”。点击构建和运行。示例应用程序会自动在默认浏览器中打开Web应用程序。

目标

开发一个网络应用框架是很困难的。有许多事情需要考虑和处理。这是我们第一次尝试网络应用框架，所以我们只关注了以下几件事

• 易于嵌入：将网络应用嵌入到原生iOS或OS X应用中应该很简单。想象一下，您正在编写一个小型的iOS应用来管理几张照片。如果您的应用能够有一个嵌入的网络应用，允许用户通过桌面电脑上的浏览器向应用中添加新照片，不是很好吗？这类事情应该很容易做到。
• 简单：OCFWeb的API非常简单。如果您了解OCFWeb的2-3个特定类，您就可以开始了。我们还尝试将您需要编写的样板代码量减少到最小。
• 轻量级：OCFWeb自身是一个相对较小的类集合。上次统计时，它有不到1K行代码。说实话：这么紧凑的原因是我们有一些依赖项，稍后会讨论。
• 异步：响应请求应该很容易。
• 易于妥协：让我们面对现实：一个有不到1K行代码的网络应用框架不能处理所有事情。实际上，这样一个小的框架只能很好地处理几个选定的场景。目前，没有内置对HTTP会话、cookies、身份验证、加密、HTTPS、持久性和安全性的支持。OCFWeb不是被设计为暴露在互联网上的。在Objective-Cloud.com，我们在每个（OCF）网络应用之前都有代理以消除关键的缺失部分。如果您在自己的应用中嵌入OCFWeb，让用户控制您的Web应用的生命周期是一个好主意。

响应类型

第一个示例展示了如何轻松创建对传入请求的响应。如您所见，分配给 GET / 路由的处理程序块。当处理程序块创建/计算出一个响应对象时，它将通过执行 respondWith-块传递到您的 OCFWebApplication 实例：request.respondWith(response)。已经提到，respondWith-块的唯一参数是以 id 类型。这允许您传递不同类型的响应对象：在某些情况下，一个简单的字符串就是一个不错的选择，而在其他情况下，您可能需要更复杂的东西。以下是您可以返回的不同类型的响应对象

• 一个简单的字符串：这将创建一个状态码为 201 的 HTTP 响应，内容类型为 plain/text，体将是你返回的字符串的 Unicode 表示。
• 一个字典：这允许您指定自定义状态码、体和自定义头部。返回的字典应类似于以下内容：@{@"status" : @201, @"headers": @{"Content-type" : @"image/tiff" }, @"body" : [image TIFFRepresentation]}
• OCFResponse 对象：OCFResponse 是一个代表响应的类。您可以选择创建和传递 OCFResponse 以实现完全控制。
• OCFMustache 对象：OCFMustache 是一个代表 Mustache 模板响应的类。目前 Mustache 是 OCFWeb 支持的唯一模板引擎。您可以在您的应用程序包中放置模板文件，然后通过使用 +newMustacheWithName:object: 创建一个 OCFMustache 对象，将模板渲染出来以便发送给客户端。

示例：字符串响应

以下示例展示了如何通过返回一个简单字符串来创建响应。

self.app = [OCFWebApplication new];    
self.app[@"GET"][@"/"] = ^(OCFRequest *request) {
  request.respondWith(@{ @"Hello World. I am a string." });
};
[self.application runOnPort:8080];

这创建了一个状态码为 201 的 plain/text 响应。如果您不喜欢字符串响应的内容类型或状态码，您可以按应用程序基础进行更改。

示例：字典响应

以下示例展示了如何通过返回一个字典来创建响应。如果您运行此示例，您应该能够使用浏览器访问显示您应用程序图标的网络应用程序。

self.app = [OCFWebApplication new];    
self.app[@"GET"][@"/"] = ^(OCFRequest *request) {
  NSImage *image = [NSImage imageNamed:@"NSApplicationIcon"];
  request.respondWith(@{ @"status" : @201,
                         @"body" : [image TIFFRepresentation],
                         @"headers" : @{ @"Content-Type" : @"image/tiff" }});
};
[self.application runOnPort:8080];

示例：Mustache 响应

为了使以下示例工作，必须在您的应用程序资源中有名为 Detail.mustache 的文件。在 使用 Mustache 响应之前，您应该阅读OCFWeb 使用的 Mustache 库的文档。Mustache 文件基本上包含带有占位符的文本，底层的 Mustache 引擎可以自动填充这些详细信息。

self.app = [OCFWebApplication new];
self.app[@"GET"][@"/"]  = ^(OCFRequest *request) {
  NSDictionary *person = @{ @"id" : @1,
                            @"firstName" : @"Christian",
                            @"lastName" : @"Kienle" };
  OCFMustache *response = [OCFMustache newMustacheWithName:@"Detail"
                                                    object:person];
  request.respondWith(response);
};
[self.app runOnPort:8080];

路由和参数

添加请求处理程序时，您必须指定一个 HTTP 方法和路径。在上面的示例中，我们使用了 GET 作为 HTTP 方法，/ 作为路径。虽然 OCFWeb 允许您进行更复杂的操作。

您指定的 HTTP 方法可以是一个正则表达式。例如：这允许您将所有请求（无论请求方法）路由到一个单一的处理程序（使用 @"^.+$" 作为方法）。应该提到，这样做被认为是坏习惯。如果您有针对不同 HTTP 方法的完全相同的处理程序，您应该重新考虑您的架构。

路径可以包含占位符的模板。占位符以 : 开头。这对于具有层次式 URL/路径（如以下示例）是有用的

• GET /countries/：列出所有国家。
• GET /countries/Germany/：仅列出名为 Germany 的国家。
• GET /countries/Germany/states/Berlin/：仅列出德国的柏林州。

假设您想要添加和实现一个显示特定状态的处理器，您可以通过使用路径模式 /countries/:country/states/:state/ 来实现。

示例：具有占位符的路由

以下示例展示了如何注册一个处理器，只有当请求路径与特定模式匹配时才会执行。

self.app = [OCFWebApplication new];
self.app[@"GET"][@"/countries/:country/states/:state/"] = ^(OCFRequest *request) {
  request.respondWith([request.parameters description]);
};
[self.application run];

使用的模式（/countries/:country/states/:state/）有两个占位符

1. 国家
2. 州

如果有匹配路径的请求进入（GET /countries/Germany/states/Berlin），则将执行指定的处理器。传入处理器的 parameters 属性是一个字典，其中包含两个键值对

1. 国家 = 德国
2. 州 = 柏林

在这种情况下，请求处理器简单地返回字典的描述。因此，您不必自己解析请求路径。

查找处理器

关于您添加的处理器的数量没有限制。如果收到请求，则必须从多个处理器中挑选一个并执行。OCFWeb应用程序通过以下两个步骤为传入请求找到处理器

1. 在第一个步骤中，OCFWeb应用程序仅使用请求的HTTP方法来查找可以处理该类型请求的处理程序：如果请求是GET请求，则确定所有可以处理GET请求的处理程序。将这些处理器称为 处理器候选人。从现在起忽略剩余的处理器。
2. 对于每个 处理器候选人，其路径模式将evaluate against the HTTP请求的路径。第一个路径与模式匹配的处理器将执行。

需求和依赖关系

OCFWeb在以下操作系统上运行

• OS X 10.8+
• iOS 6+

目前，OCFWeb有以下依赖关系（也列在Podfile中）

• OCFWebServer：用于创建HTTP服务器。
• SOCKit：用于路径模式（匹配）。
• GRMustache：用于mustache响应。

谁在使用OCFWeb？

OCFWeb由Objective-Cloud.com使用。我们计划向在Objective-Cloud.com上托管应用程序的开发者开放OCFWeb的部分。

如何贡献

OCFWebServer的开发在GitHub上进行。如果您发现错误、怀疑有错误或有问题，请随时创建问题。Pull请求非常欢迎，并且将尽快接受。

许可

OCFWeb采用MIT许可（MIT）。