使用 Rational Software Architect 设计和实现 RESTful Web 服务

RESTful Web 服务的模型驱动开发

建模 RESTful Web 服务是 Rational Software Architect 的一项新功能。在解释 REST 建模功能的过程中,作者展示了如何根据 UML 模型设计和实现 RESTful 书签服务。您可以利用这项新功能和新知识来创建模型,在开发之前和开发期间向别人解释您的 Web 服务模型。这种模型方法的模型使您向别人解释自己的项目变得更加简单明了。它也可以成为用户文档的一部分。

Sandeep Katoch, 高级软件工程师, IBM

作者照片Sandeep Katoch 在 Rational Software Architect 开发团队工作。他在 IT 行业拥有超过 12 年的工作经验。他酷爱建模,在过去 5 年一直致力于 IBM 建模工具的开发。



2012 年 11 月 19 日

下载 Rational® Software Architect 试用版  |  Rational® Software Architect Design Manager 试用版
下载更多的 IBM 软件试用版,并加入 IBM 软件下载与技术交流群组,参与在线交流。

简介

REST(具象状态传输)是一种架构形式,支持使用 HTTP 协议开发松散耦合系统。从传统上讲,已在每个资源以及它们的代表支持的 URI、资源和 HTTP 方法中描述了基于 REST 服务(或 RESTful Web 服务)的设计。通常将此类描述发布为文档,以支持实现服务,并支持服务的客户端识别和使用 Web 服务。由于缺少正式标注,所以此类描述总是以文本和表格的形式出现在设计文档中,这为这种方法带来了一些挑战:

  1. 如何设计 RESTful Web 服务?
  2. 如何实现此设计?
  3. 如何发布 RESTful 服务,使其可供用户使用?
  4. 如何发展此设计和实现?

IBM® Rational® Software Architect Version 8.0.3 使用 RESTful Web 服务建模和实现支持在模型驱动开发范式中解决了这些挑战。建模支持允许您为 Web 服务创建 UML 模型来描述 Web 服务。同一 UML 模型还用作针对那些使用您的 Web 服务的人员生成文档的来源。在实现方面,您可以生成 Java 代码,以便使用 Java API for RESTful Web Services 或 JAX-RS 生成 Web 服务。

出于这种考虑,让我们来研究一下 Rational Software Architect 的 REST 建模功能。在本文结尾部分,您将能够根据图 1 所示的 UML 模型来设计和实现 RESTful 书签服务。

图 1. RESTful 书签 Web 服务模型
RESTful Web 服务元素的 UML 类图

设计 Web 服务

RESTful Web 服务设计从 UML 模型开始。Rational Software Architect 包含您的设计依据的两个模板模型(如图 2 所示)。

图 2. REST 模型模板
可用的模型类别列表和 REST 模板

如果 RESTful 服务的最终实现将基于 JAX-RS,请选择 JAX-RS Service Model 模板。如果您还没有考虑实现或者是不想使用 JAX-RS,那么可以选择 REST Service Model 模板。这些模型模板预设了建模服务所需的各种面板和库。

创建了模型后,通常会看到模型的主图。在此图中,您可以在左侧看到 REST 面板(可以使用此面板创建 REST 元素),在右侧看到选择模型元素的面板。

图 3. 主图和 REST 面板
图面板上可用的 REST 模型元素

您可以使用此面板创建构成 RESTful Web 服务的各种元素。

首先创建应用程序。

  1. 单击 Application Class 面板项,然后在图的空白区域单击。
  2. 将此类命名为 BookmarkApplication。此应用程序类表示 RESTful Web 服务的 root。
  3. 接下来,您可以添加此应用程序应显示的 RESTful 资源。

每种资源都会显示在一个 URI 上,它可以支持任何 HTTP 方法。例如,对于 Bookmark Web 服务,您能够以表 1 所示的方式显示资源。

表 1. 资源和 URI
资源URI受支持的 HTTP 方法
Users /users GET getListofUsers
POST createUser
User /users/{username}GET getUser
DELETE deleteUser
Bookmarks /users/{username}/bookmarksGET getListofBookmarks
POST createBookmark
Bookmark /users/{username}/bookmarks/{bookmarkId}GET getBookmark
DELETE deleteBookmark

根据此表,您可以通过应用程序的 root 上的 /users URI 访问 Users 资源。

  1. 要创建资源,可以单击面板中的 Resource Class,然后在图的空白区域单击,将此类命名为 Users。
  2. REST URI 被建模为路径。因此,要建模 /user URI,请单击面板中的 Path Dependency 项,然后单击图中的 BookmarkApplication 类,并将该类拖动到 Users 类,将此路径命名为 /users

接下来,您可以添加此资源支持的 REST 方法。

对于 Users 资源,软件支持 HTTP GET 和 POST 方法,因此您可以单击 GET operation,然后单击图中的 Users 类,并将此操作命名为 getListofUsers

类似地,为 POST 操作重复这些操作,并将操作命名为 createUser

注意:
从 REST 角度看,这些是 GET 和 POST HTTP 方法,但是在这里,用更具描述性的名称命名了它们。

现在,您的图类似于图 4。

图 4. BookmarkApplication 和 Users 图
在 Application 和 Resource 之间绘制的 REST 路径
  1. 现在,您可以添加剩余的资源、路径和操作。

最终得到的图表将类似于图 5。

图 5. UML 模型
书签 Web 服务的类图

图 5 的大图

对于 User 资源的 getUser GET 操作,请注意 URI 是 /users/{username}。在这里,{username} 是此资源的参数。要在 getUser 操作中指定其用法,请单击面板中的 Param parameter,然后单击主图的 getUser 操作。这将为此操作创建一个参数。

注意:
创建了参数后,可能在图上看不到参数。这是因为,默认情况下,从图上过滤了参数。要使该参数可见,请右键单击图中的 User 类,并选择 Filter > Show Signature

可以在 Properties 视图的 REST 选项卡中指定此参数的详细信息(参见图 6)。对于此参数,请选择 PathParam(因为它是从路径中提取的),并选择 username 作为名称。还可以将此参数指定为 Header 参数或 Query 参数等参数,具体取决于您的设计。此外,您可以指定默认值。

图 6. REST 参数选项卡
REST 参数的 Properties 视图
图 6. REST 参数选项卡
REST 参数的 Properties 视图

为了保持一致性,我们建议您将此参数的 UML 名称与 REST 名称保持一致(或相似)。

  1. 为此,可以切换到 General 选项卡,并将名称更改为 username
  2. 在 General 选项卡中,还可以将参数的 UML type 指定为 String

REST type (PathParam) 和 UML type (String) 的差别是,REST type 是 REST 接口上供用户访问 REST 服务的类型,而 UML type 是实现 REST 服务奖使用的参数类型。

对于每种 REST 方法,还需要将数据格式指定为支持输入和输出的格式。

  1. 选择 getUser 方法,并切换到 Properties 视图中的 REST 选项卡。
  2. 在 Produces(或 Consumes)列表内,通过单击来指定格式。

有一组预定义值可供您选择(参见图 7),您也可以输入所选的类型。对于 Produces 和 Consumes,可以指定多个类型。

  1. 在 Produces 部分,选择 application/xml
图 7. REST 方法生成和使用的属性
REST 方法的 Properties 视图

在此选项卡的最下方,您可以指定此方法可以返回的 HTTP 返回码。

  1. Return codes 列表内部单击以选择返回码。
  2. 选择 200 OK 作为一个返回码,并选择 404 Not Found 作为另一个返回码。

下拉菜单中有标准的 HTTP 返回码可供选择,您也可以输入自己的自定义代码。对于每个返回码,可以指定返回的内容示例,并在 Content 和 Description 文本框中添加描述。

图 8. REST 方法返回码属性
REST 方法返回码的 Properties 视图

在序列图中建模 RESTful 交互

您可以使用序列图建模与 RESTful Web 服务的客户端之间的典型交互。客户端和服务之间的调用基本上是 HTTP 调用,因此,在 HTTPReference 库中提供了一个 HTTP 交互元素(参见图 9)。

图 9. HTTP 交互元素
可用的 HTTP 交互元素

如果您使用 REST 或 JAX-RS 模板模型创建了模型,则已将 HTTPReference 导入您的模型中。

HTTP 交互元素用于表示客户端和 RESTful Web 服务。

  1. 要在序列图中使用此元素,请单击 HTTP Interaction 元素,并将该元素从 Project Explorer 拖放到序列图上,对其进行适当命名,例如,对于客户端,请将它命名为 Client,而对于 Web 服务,请将它命名为 Bookmark Service
  2. 现在,您可以在客户端和 Web 服务之间绘制消息。
  3. 在绘制每条消息时,可以从 HTTP Requests and Responses 列表的下拉菜单中为消息选择操作类型(参见图 10)。通常情况下,对于从客户端到 Web 服务的消息,可以选择 GET、POST 和 DELETE 请求。
图 10. 序列图的 HTTP 请求
可用的序列图 HTTP 方法
  1. 对于 return,请选择返回码,比如 200 OK
图 11. 序列图的 HTTP 响应
可用的序列图 HTTP 返回码
  1. 对于消息,还可以使用 HTTP Properties 选项卡,以 URI、标头和内容的形式详细描述每个请求或响应(参见图 12)。
图 12. HTTP 方法详细信息
HTTP 方法的 Properties 视图

序列图支持对于 Web 服务的客户端了解支持的工作流非常有用。

  1. 对于实现方法,可以使用实际资源类的调用来详细描述序列图,方法是将资源类拖放到序列图,并将消息绘制到序列图。
图 13. 实现的序列图
序列图的 RESTful 交互

使用 BIRT 报表生成文档

Business Intelligence and Reporting Tools (BIRT) 报表是共享或发布 RESTful Web 服务文档的一种简单方式。Rational Software Architect 包含一个与 REST Models 一起使用的 REST 报表模板。您还可以根据文档需要编辑和改进报表。

  1. 要创建 REST 报表,请选择 File > New > Other > REST Modeling Reports > REST Report
图 14. REST 报表
REST 模型的 BIRT 报表

使用 JAX-RS 实现 Web 服务

准备好模型后,可以组合使用 UML-to-Java 转换和 JAX-RS extension 来生成服务的实现。但是,在进行此操作前,需要为模型添加一些 JAX-RS 详细信息。

第一条详细信息是子资源定位符操作。在 REST 模型中,绘制了 Path dependency 来提供资源间的导航。

  1. 在 JAX-RS 实现中,需要在源资源中创建子资源定位符操作。可以从面板创建 SubResourceLocator 方法。
图 15. JAX-RS 面板
图面板上可用的 JAX-RS 模型元素
  1. 为了完全定义定位符操作,需要将其返回类型设置为目标资源,并将其定位器原型属性(即 SubResourceLocator)设置为 path 值(在本示例中为 <Path/bookmarks>),如图 16 所示。
图 16. Sub-Resource Locator 属性
JAX-RS 定位符操作属性视图
  1. 还需要为您的操作添加 JAX-RS 具体类型。

例如,您可能想要使用 javax.ws.rs.core.Response 对象作为返回类型。JAX-RS 参考库提供了这些类型(参见图 17)。

图 17. JAX-RS 参考库
参考库中的 JAX-RS 模型元素
  1. 现在,您可以创建 UML-to-Java 转换配置来生成服务的代码。配置源应该是您创建的模型,并且目标应该是一个 JAX-RS 库支持的动态 Web 项目。
  2. 您还需要在转换配置的 extensions 选项卡中启用 JAX-RS UML-to-Java5 扩展(参见图 18)。
图 18. JAX-RS UML-to-Java5 转换扩展
从可用的 UML-to-Java 扩展中选择

此扩展自动生成 Java 类的 JAX-RS 注释和服务所需的 web.xml 文件更新。

  1. 运行此转换将生成实现所需的 Java 类,您还可以为您的类添加所需的实现逻辑。

现在,您可以打包此应用程序,并在 IBM® WebSphere® Application Server with Feature Pack for Web 2.0 and Mobile(支持 JAX-RS)上部署此应用程序。

  1. 如果您在 WebSphere Application Server Test Environment 中安装了 Rational Software Architect,可以右键单击动态 Web 项目,并选择 Debug As > Debug on Server,然后选择测试服务器。

在此之后,您可以在 Rational Software Architect 环境中测试并调试 RESTful Web 服务。

注意:
可以使用任意 JAX-RS 实现部署实现(例如 Apache Wink)。没有必要使用 WebSphere Application Server。

组合使用 UML-to-Java 转换和 JAX-RS 扩展,这将提供双向工程的完整支持。因此,您可以建模和生成代码,并在稍后完善模型和更新代码,或者是更新代码,在 Reconcile 模式下使用 UML-to-Java 转换从代码更新模型。

如果您已经有了一个基于 JAX-RS 的现有动态 Web 项目,可以组合使用 Java-to-UML 转换和 JAX-RS 扩展从项目生成 UML 模型。您可以将本文作为您理解现有 JAX-RS 实现并进一步完善它们的一个好起点。


结束语

本文简要介绍了 JAX-RS 支持。后续文章将详细地介绍 JAX-RS。

您已经了解了在 Rational Software Architect 中如何使用模型驱动的开发支持进行建模并实现 RESTful Web 服务。基于模型的方法使 RESTful Web 服务的设计、实现和发展变得更加简单。

您可以下载 Bookmark 服务模型来进一步探索(参阅 下载 部分)。此外,您将在本文的 参考资料 部分找到更多有用的信息。


下载

描述名字大小
书签服务 UML 模型Bookmarks_Service_Model.zip6KB

参考资料

学习

获得产品和技术

讨论

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Rational
ArticleID=846533
ArticleTitle=使用 Rational Software Architect 设计和实现 RESTful Web 服务
publish-date=11192012