|
编者按：《通过demo学习OpenStack开发》专栏是刘陈泓的系列文章，专栏通过开发一个demo的形式来介绍一些参与OpenStack项目开发的必要的基础知识，希望帮助大家入门企业级Python项目的开发和OpenStack项目的开发。刘陈泓主要关注OpenStack的身份认证和计费领域。另外，还对云计算、分布式系统应用和开发感兴趣。
上一篇文章说到，我们将以实例的形式来继续讲述这个API服务的开发知识，这里会使用Pecan和WSME两个库。
设计REST API
要开发REST API服务，我们首先需要设计一下这个服务。设计包括要实现的功能，以及接口的具体规范。我们这里要实现的是一个简单的用户管理接口，包括增删改查等功能。如果读者对REST API不熟悉，可以先从Wiki页面了解一下。
另外，为了方便大家阅读和理解，本系列的代码会放在github上，diabloneo/webdemo。
Version of REST API
在OpenStack的项目中，都是在URL中表明这个API的版本号的，比如Keystone的API会有/v2.0和/v3的前缀，表明两个不同版本的API；Magnum项目目前的API则为v1版本。因为我们的webdemo项目才刚刚开始，所以我们也把我们的API版本设置为v1，下文会说明怎么实现这个version号的设置。
REST API of Users
我们将要设计一个管理用户的API，这个和Keystone的用户管理的API差不多，这里先列出每个API的形式，以及简要的内容说明。这里我们会把上面提到的version号也加入到URL path中，让读者能更容易联系起来。
这些就是我们要实现的用户管理的API了。其中，表示使用一个UUID字符串，这个是OpenStack中最经常被用来作为各种资源ID的形式，如下所示：
因为是个demo，所以我们设置一个用户包含的信息会比较简单，只包含name和age。
使用Pecan搭建API服务的框架
接下来就要开始编码工作了。首先要把整个服务的框架搭建起来。我们会在软件包管理这篇文件中的代码基础上继续我们的demo（所有这些代码在github的仓库里都能看到）。
代码目录结构
一般来说，OpenStack项目中，使用Pecan来开发API服务时，都会在代码目录下有一个专门的API目录，用来保存API相关的代码。比如Magnum项目的magnum/api，或者Ceilometer项目的ceilometer/api等。我们的代码也遵守这个规范，让我们直接来看下我们的代码目录结构（#后面的表示注释）：
这个在API服务(3)这篇文章中已经说明过了。
先让我们的服务跑起来
为了后面更好的开发，我们需要先让我们的服务在本地跑起来，这样可以方便自己做测试，看到代码的效果。不过要做到这点，还是有些复杂的。
必要的代码
首先，先创建config.py文件的内容：
就是包含了Pecan的最基本配置，其中指定了root controller的位置。然后看下app.py文件的内容，主要就是读取config.py中的配置，然后创建一个WSGI application：
然后，我们至少还需要实现一下root controller，也就是webdemo/api/controllers/root.py这个文件中的RootController类：
本地测试服务器
为了继续开放的方便，我们要先创建一个Python脚本，可以启动一个单进程的API服务。这个脚本会放在webdemo/cmd/目录下，名称是api.py（这目录和脚本名称也是惯例），来看看我们的api.py吧：
运行测试服务器的环境
要运行这个测试服务器，首先需要安装必要的包，并且设置正确的路径。在后面的文章中，我们将会知道，这个可以通过tox这个工具来实现。现在，我们先做个简单版本的，就是手动创建这个运行环境。
首先，完善一下requirements.txt这个文件，包含我们需要的包：
然后，我们手动创建一个virtualenv环境，并且安装requirements.txt中要求的包：
启动我们的服务
启动服务需要技巧，因为我们的webdemo还没有安装到系统的Python路径中，也不在上面创建virtualenv环境中，所以我们需要通过指定PYTHONPATH这个环境变量来为Python程序增加库的查找路径：
现在测试服务器已经起来了，可以通过浏览器访问http://localhost:8080/ 这个地址来查看结果。（你可能会发现，返回的是XML格式的结果，而我们想要的是JSON格式的。这个是WSME的问题，我们后面再来处理）。
到这里，我们的REST API服务的框架已经搭建完成，并且测试服务器也跑起来了。
用户管理API的实现
现在我们来实现我们在第一章设计的API。这里先说明一下：我们会直接使用Pecan的RestController来实现REST API，这样可以不用为每个接口指定接受的method。
让API返回JSON格式的数据
现在，所有的OpenStack项目的REST API的返回格式都是使用JSON标准，所以我们也要这么做。那么有什么办法能够让WSME框架返回JSON数据呢？可以通过设置wsmeext.pecan.wsexpose()的rest_content_types参数来是先。这里，我们借鉴一段Magnum项目中的代码，把这段代码存放在文件webdemo/api/expose.py中：
这样我们就封装了自己的expose装饰器，每次都会设置响应的content-type为JSON。上面的root controller代码也就可以修改为：
再次运行我们的测试服务器，就可以返现返回值为JSON格式了。
实现 GET /v1
这个其实就是实现v1这个版本的API的路径前缀。在Pecan的帮助下，我们很容易实现这个，只要按照如下两步做即可：
先实现v1这个controller
把v1 controller加入到root controller中
按照OpenStack项目的规范，我们会先建立一个webdemo/api/controllers/v1/目录，然后将v1 controller放在这个目录下的一个文件中，假设我们就放在v1/controller.py文件中，效果如下:
然后把这个controller加入到root controller中：
此时，你访问http://localhost:8080/v1就可以看到结果了。
实现 GET /v1/users
添加users controller
这个API就是返回所有的用户信息，功能很简单。首先要添加users controller到上面的v1 controller中。为了不影响阅读体验，这里就不贴代码了，请看github上的示例代码。
使用WSME来规范API的响应值
上篇文章中，我们已经提到了WSME可以用来规范API的请求和响应的值，这里我们就要用上它。首先，我们要参考OpenStack的惯例来设计这个API的返回值：
其中users是一个列表，列表中的每个元素都是一个user。那么，我们要如何使用WSME来规范我们的响应值呢？答案就是使用WSME的自定义类型。我们可以利用WSME的类型功能定义出一个user类型，然后再定义一个user的列表类型。最后，我们就可以使用上面的expose方法来规定这个API返回的是一个user的列表类型。
定义user类型和user列表类型
这里我们需要用到WSME的Complex types的功能，请先看一下文档Types。简单说，就是我们可以把WSME的基本类型组合成一个复杂的类型。我们的类型需要继承自wsme.types.Base这个类。因为我们在本文只会实现一个user相关的API，所以这里我们把所有的代码都放在webdemo/api/controllers/v1/users.py文件中。来看下和user类型定义相关的部分：
这里我们定义了class User，表示一个用户信息，包含两个字段，name是一个文本，age是一个整型。class Users表示一组用户信息，包含一个字段users，是一个列表，列表的元素是上面定义的class User。完成这些定义后，我们就使用WSME来检查我们的API是否返回了合格的值；另一方面，只要我们的API返回了这些类型，那么就能通过WSME的检查。我们先来完成利用WSME来检查API返回值的代码：
这样就完成了API的返回值检查了。
实现API逻辑
我们现在来完成API的逻辑部分。不过为了方便大家理解，我们直接返回一个写好的数据，就是上面贴出来的那个。
代码中，会先根据user信息生成User实例的列表users_list，然后再生成Users实例。此时，重启测试服务器后，你就可以从浏览器访问http://localhost:8080/v1/users，就能看到结果了。
实现 POST /v1/users
这个API会接收用户上传的一个JSON格式的数据，然后打印出来（实际中一般是存到数据库之类的），要求用户上传的数据符合User类型的规范，并且返回的状态码为201。代码如下：
可以使用curl程序来测试：
同时，服务器上也会打印出：
我们用3行代码就实现了这个POST的逻辑。现在来说明一下这里的秘密。expose装饰器的第一个参数表示这个方法没有返回值；第三个参数表示这个API的响应状态码是201，如果不加这个参数，在没有返回值的情况下，默认会返回204。第二个参数要说明一下，这里用的是body=User，你也可以直接写User。使用body=User这种形式，你可以直接发送符合User规范的JSON字符串；如果是用expose(None, User, status_code=201)那么你需要发送下面这样的数据：
你可以自己测试一下区别。要更多的了解本节提到的expose参数，请参考WSM文档Functions。
最后，你接收到一个创建用户请求时，一般会为这个用户分配一个id。本文前面已经提到了OpenStack项目中一般使用UUID。你可以修改一下上面的逻辑，为每个用户分配一个UUID。
实现 GET /v1/users/
要实现这个API，需要两个步骤：
在UsersController中解析出的部分，然后把请求传递给这个一个新的UserController。从命名可以看出，UsersController是针对多个用户的，UserController是针对一个用户的。
在UserController中实现get()方法。
使用_lookup()方法
Pecan的_lookup()方法是controller中的一个特殊方法，Pecan会在特定的时候调用这个方法来实现更灵活的URL路由。Pecan还支持用户实现_default()和_route()方法。这些方法的具体说明，请阅读Pecan的文档：routing。
我们这里只用到_lookup()方法，这个方法会在controller中没有其他方法可以执行且没有_default()方法的时候执行。比如上面的UsersController中，没有定义/v1/users/如何处理，它只能返回404；如果你定义了_lookup()方法，那么它就会调用该方法。
_lookup()方法需要返回一个元组，元组的第一个元素是下一个controller的实例，第二个元素是URL path中剩余的部分。
在这里，我们就需要在_lookup()方法中解析出UUID的部分并传递给新的controller作为新的参数，并且返回剩余的URL path。来看下代码：
_lookup()方法的形式为_lookup(self, user_id, *remainder)，意思就是会把/v1/users/中的部分作为user_id这个参数，剩余的按照”/”分割为一个数组参数（这里remainder为空）。然后，_lookup()方法里会初始化一个UserController实例，使用user_id作为初始化参数。这么做之后，这个初始化的控制器就能知道是要查找哪个用户了。然后这个控制器会被返回，作为下一个控制被调用。请求的处理流程就这么转移到UserController中了。
实现API逻辑
实现前，我们要先修改一下我们返回的数据，里面需要增加一个id字段。对应的User定义如下：
现在，完整的UserController代码如下：
使用curl来检查一下效果：
定义WSME类型的技巧
你可能会有疑问：这里我们修改了User类型，增加了一个id字段，那么前面实现的POST /v1/users会不会失效呢？你可以自己测试一下。（答案是不会，因为这个类型里的字段都是可选的）。这里顺便讲两个技巧。
如何设置一个字段为强制字段
像下面这样做就可以了（你可以测试一下，改成这样后，不传递id的POST /v1/users会失败）：
如何检查一个可选字段的值是否存在
检查这个值是否为None是肯定不行的，需要检查这个值是否为wsme.Unset。
实现 PUT /v1/users/
这个和上一个API一样，不过_lookup()方法已经实现过了，直接添加方法到UserController中即可：
通过curl来测试：
实现 DELETE /v1/users/
同上，没有什么新的内容：
总结
到此为止，我们已经完成了我们的API服务了，虽然没有实际的逻辑，但是本文搭建起来的框架也是OpenStack中API服务的一个常用框架，很多大项目的API服务代码都和我们的webdemo长得差不多。最后再说一下，本文的代码在github上托管着：diabloneo/webdemo。
现在我们已经了解了包管理和API服务了，那么接下来就要开始数据库相关的操作了。大部分OpenStack的项目都是使用非常著名的sqlalchemy库来实现数据库操作的，本系列接下来的文章就是要来说明数据库的相关知识和应用。
|
