简介

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 书签服务。

回页首

设计 Web 服务

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

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

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

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

首先创建应用程序。

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

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

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

4. 要创建资源，可以单击面板中的 Resource Class，然后在图的空白区域单击，将此类命名为 Users。
5. 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。

6. 现在，您可以添加剩余的资源、路径和操作。

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

图 5 的大图

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

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

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

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

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

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

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

9. 选择 getUser 方法，并切换到 Properties 视图中的 REST 选项卡。
10. 在 Produces（或 Consumes）列表内，通过单击来指定格式。

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

11. 在 Produces 部分，选择 application/xml。

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

12. 在 Return codes 列表内部单击以选择返回码。
13. 选择 200 OK 作为一个返回码，并选择 404 Not Found 作为另一个返回码。

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

回页首

在序列图中建模 RESTful 交互

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

如果您使用 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 请求。

4. 对于 return，请选择返回码，比如 200 OK。

5. 对于消息，还可以使用 HTTP Properties 选项卡，以 URI、标头和内容的形式详细描述每个请求或响应（参见图 12）。

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

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

回页首

使用 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。

回页首

使用 JAX-RS 实现 Web 服务

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

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

1. 在 JAX-RS 实现中，需要在源资源中创建子资源定位符操作。可以从面板创建 SubResourceLocator 方法。

2. 为了完全定义定位符操作，需要将其返回类型设置为目标资源，并将其定位器原型属性（即 SubResourceLocator）设置为 path 值（在本示例中为 <Path/bookmarks>），如图 16 所示。

3. 还需要为您的操作添加 JAX-RS 具体类型。

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

4. 现在，您可以创建 UML-to-Java 转换配置来生成服务的代码。配置源应该是您创建的模型，并且目标应该是一个 JAX-RS 库支持的动态 Web 项目。
5. 您还需要在转换配置的 extensions 选项卡中启用 JAX-RS UML-to-Java5 扩展（参见图 18）。

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

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

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

7. 如果您在 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 服务模型来进一步探索（参阅 下载 部分）。此外，您将在本文的 参考资料 部分找到更多有用的信息。

回页首

下载

关于下载方法的信息

参考资料

学习

• 务必查看与本文相关的这些资源：
  • 要了解有关 Rational Software Architect 的更多信息，从 developerWorks Rational Software Architect 产品专题 开始。另请参见 Rational Software Architect 产品概述 和 Rational Software Architect 信息中心，了解有关的安装和使用说明，并访问 Rational Software Architect 维基，获得更多资源。
  • 访问此 Rational Software Architect 维基主题 RSA v8 What's New, Generating of REST-style services 中的 REST 建模幻灯片和视频。
  • 获取 WebSphere Application Server Feature Pack for Web 2.0 and Mobile。
  • 了解 JSR 311: JAX-RS: The JavaTM API for RESTful Web Services，以及 Java Community Process 网站上的 Java Specification Requests。
  • 您还可能会发现博客文章 An example of modeling REST web services 非常有用。
  
  
• 访问 developerWorks 上的 Rational 软件专区，获得 Rational Software Delivery Platform 产品的技术资源和最佳实践。
  
  
• 随时关注 developerWorks 技术活动和网络广播，了解各种 IBM 产品和 IT 行业主题。
  • 参加 developerWorksLive! 技术讲座，快速了解 IBM 产品和工具，以及 IT 行业趋势。
  • 观看 developerWorks 演示中心，那里提供了面向初学者的产品安装和设置演示，以及面向经验丰富的开发人员的高级功能。
  
  
• 提高您的技能。查看 Rational 培训和认证 目录，其中包含了许多广泛议题的课程类型。您可以随时随地学习它们，许多 “入门” 课程都是免费的。
  
  

获得产品和技术

• 下载其中一个试用版或者同时下载两个试用版：
  • Rational Software Architect Standard Edition
  • Rational Software Architect for WebSphere Software
  
  
• 以最适合您的方式评估 IBM 产品试用版软件：下载产品试用版，在线试用产品，在云环境下试用产品，或者在 IBM SOA 人员沙箱 中花费几个小时来学习如何高效实现面向服务的架构。
  
  

讨论

• 参与 Rational Development Tools 论坛 的讨论。
  
  
• 评分或评论 Rational 软件。以这种方式进行评分和评论会既快又简单。
  
  
• 通过撰写一篇 developerWorks 文章，分享您的知识并帮助其他使用 Rational 软件的人。了解 优秀的 developerWorks 文章有何特点，以及如何写出好文章。
  
  
• 在 Facebook、Twitter (@ibmrational) 和 YouTube 上关注 Rational 软件，并发表您的评论和请求。
  
  
• 加入 Rational forums、Rational cafés 和 wikis，提出问题并回答问题，提高您的专业知识。
  
  
• 与思想领袖进行交流。加入 Rational 社区，与同行交流并共享 Rational 软件专业知识。
  
  

关于作者

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

为本文评分

评论

回页首

内容

• 简介
• 设计 Web 服务
• 在序列图中建模 RESTful 交互
• 使用 BIRT 报表生成文档
• 使用 JAX-RS 实现 Web 服务
• 结束语
• 下载
• 参考资料
• 关于作者
• 评论