定义product.proto文件的过程如下。

syntax = "proto3";//声明支持的版本是proto 3 option java_package = "com.cloudnative.protobuf";//声明包名，可选 option java_outer_classname="ProductProtos";//声明类名，可选 message Product { int32 id = 1; string name = 2; string price = 3; enum ColorType {//定义枚举类型 WHITE = 0; RED = 1; BLACK = 2; } }

在命令行执行如下代码。

protoc --java_out=../java product.proto

--java_out表示在目标目录中生成Java代码。由于已将product.proto放到src/mian/java/proto目录下，所以--java_out=../java参数会将生成的Java类创建到java目录下，如图2-14所示。

图2-14 项目目录结构

打开ProtobufProtos会发现，这是一个非常复杂的类，其代码大概1500行。

4．使用Protobuf序列化

引入Protobuf-java包，可以先通过http://mvnrepository.com查询，然后点击复制，非常方便，如图2-15所示。

图2-15 查询结果

实际上，Protobuf的序列化及反序列化非常简单。Protobuf生成的类中已经实现了相应的方法，调用即可。示例代码如下。

package com.cloudnative.protobuf; import com.google.protobuf.InvalidProtocolBufferException; public class TestProtobuf { public static void main(String[] args){ TestProtobuf testProtobuf =new TestProtobuf(); byte[] buf=testProtobuf.toByte(); try { ProductProtos.Product product = testProtobuf.toProduct(buf); System.out.println(product); } catch (InvalidProtocolBufferException e) { e.printStackTrace(); } } //序列化 private byte[] toByte(){ ProductProtos.Product.Builder productBuilder=ProductProtos.Product.newBuilder(); productBuilder.setId(11); productBuilder.setName("milk"); productBuilder.setPrice("4.12"); ProductProtos.Product product =productBuilder.build(); byte[] buf = product.toByteArray(); System.out.println(buf.length); return buf; } //反序列化 private ProductProtos.Product toProduct(byte[] buf) throws InvalidProtocolBufferException { return ProductProtos.Product.parseFrom(buf); } }服务间通信——RESTful

REST是Roy Thomas Fielding在2000年的博士论文中提出的。REST是Representational State Transfer的缩写，通常翻译为“表现层状态转化”。如果一个架构符合REST原则，就称它为RESTful架构。

API如何设计才能满足RESTful的要求呢？

1．协议

API是基于HTTP的协议。

2．域名

API要有一个域名，例如http://api.xxx.com。

3．版本

API要有版本信息。当客户端数量较多或者提供给第三方使用时，很难控制客户端的兼容性，一个比较好的做法就是当已发布的服务变更时，通过版本来控制兼容性。当然，版本不能演进太快，最好的版本化就是无须版本，例如http://api.xxx.com/v1/。

4．路径

要理解REST，首先要理解什么是资源（Resource）。REST开发又被称作面向资源的开发。API要用资源来表示，URL中不能出现动词。资源是服务端可命名的一个抽象的概念，只要客户端容易理解，可以随意抽象。通常可以把资源看成是一个实体，例如用户、邮件、图片等，用URI（统一资源定位符）指向它。经验告诉我们，往往这里的资源和数据库的表名是对应关系。一种观点认为DDD可以和REST API很好地契合，因为REST的资源可以很好地与DDD的实体映射起来。定义资源的时候，推荐用复数，假设我们要获取用户的信息，大概是这样：http://api.xxx.com/v1/users/。

5．方法

一般允许的方法主要包括如下几种。

• · GET：读取资源，一个或多个（常用）。
• · POST：创建资源（常用）。
• · PUT：修改资源，客户端提供修改后的完整资源（常用）。
• · PATCH：对已知资源进行局部更新，客户端只需要提供改变的属性。
• · DELETE：删除、回收资源（常用）。
• · HEAD：读取资源的元数据（不常用）。
• · OPTIONS：读取对资源的访问权限（不常用）。

一般情况下，GET、POST、PUT、DELETE已经足够，甚至有一种观点认为，只需要使用GET、POST即可，例子如下所示。

· GET/users/1，获取用户ID为1的用户信息。

· GET/users/1/orders，获取用户ID为1的用户拥有的所有订单。

6．参数

参数可以放到API路径中，也可以放到“?”的后面。

GET/users/1/orders GET/orders?user_id=1

7．编码

虽然RESTful并没有限制资源的表达格式，HTML/XML/JSON/纯文本/图片/视频/音频等都可以，但是通常服务端和客户端通过JSON传递信息。

8．状态码

用HTTP Status Code传递Server的状态信息，常用的状态码如下。

• · 100Continue
• · 200OK，GET
• · 201Created，POST/PUT/PATCH
• · 202Accepted
• · 204NO Content，DELETE
• · 400Bad Request，POST/PUT/PATCH
• · 401Unauthorized
• · 403Forbidden
• · 404Not Found
• · 405Method Not Allowed
• · 406Not Acceptable
• · 409Conflict
• · 410Gone
• · 412Precondition Failed
• · 429Too many requests
• · 500Internal Server Error
• · 501Not Implemented
• · 503Service Unavailable

完整信息可以参考w3官网。

要理解RESTful，还要考虑如下重要的约束条件。当然，这些条件也不是绝对的，需要结合业务场景来确定。

· 单一职责。尽量保持接口职责单一，留给客户端足够的操作空间，以满足不同的业务需求。对于接口粒度的大小，需要考虑的因素包括：性能（合并请求性能更高）、一致性、灵活性及客户端的易用程度。

· 幂等性。一次和多次请求某一个资源应该具有同样的作用，客户端能够重复发起请求而不必担心造成副作用。

· 无状态。多次请求之间不应该存在状态耦合，无须关联过去、现在和将来的请求或者响应。

· 客户端发起。一般通信方式都是由客户端发起的，服务端是被调用的。随着HTTP/2的到来，这一条可能会发生变化。

· 原子性。保证所有操作是一个不可分割的单元，要么全部成功，要么全部失败，需要结合业务要求加以确定。

· 易用。需要提供详尽的文档、参数说明、示例等，API定义的URL、变量名要通俗易懂，最好是英文，尽量减少自定义的缩写，让开发者容易调试和管理。

· SLA。需要提供响应时间、吞吐量、可用性等关键指标。

RESTful已经成为业界的主流，主要是因为RESTful通常采用HTTP JSON的方式实现，继承了HTTP和JSON的优点。相对于SOAP、RPC等方式，RESTful更加轻量、简单，支持跨语言，并且容易调试。

传统的API设计通常先完成代码，然后另外补充一份说明文档，这种方式效率比较低，文档和代码缺乏关联性。更高级一点的做法是使用JAVADOC，把文档和注释关联起来，以提升效率，但是由于JAVADOC需要不断生成，文档难免和代码存在不一致。

在此背景下，Swagger诞生了。Swagger是一个简单、功能强大、非常流行的API表达工具。基于Swagger生成API，可以得到交互式文档、自动生成代码的SDK，以及API的发现方式等。通过Swagger可以很容易地生成标准的API，示例如图2-16所示。

图2-16 基于Swagger生成API的示例

Swagger是基于OpenAPI的，OpenAPI支持YAML和JSON格式描述API。YAML相对于JSON来说更加简洁，比较适合做简洁的序列化和配置文件。编写YAML文档推荐使用Swagger Editor，它提供了语法高亮、自动完成、即时预览等功能。编辑器可以在本地使用，也可以在线使用。YAML的数据结构可以用类似大纲的缩排方式呈现，结构通过缩进来表示，连续的项目通过“-”来表示，map结构里面的key/value对用“:”来分隔。

基于Swagger Editor设计API，可以直接在线编辑API，也可以在本地安装，下面以在线编辑器为例介绍如何基于Swagger构建API。

（1）访问官方Editor编辑器

http://editor2.swagger.io。

（2）编辑YAML文件，如下所示。

swagger: "2.0" info: version: 1.0.0 title: Product API description: Product API for test schemes: - https host: localhost basePath: /product paths: {}

下面简单说明一下这个文档。首先，显示OpenAPI使用的版本是2.0。

swagger: "2.0"

API的描述信息，包括如API文档版本（version）、API文档名称（title）和描述信息（description）。

info: version: 1.0.0 title: Product API description: Product API for test

下面的代码表示API的URL，采用HTTPS协议，介绍了主机名（host）、根路径（basePath）。

schemes: - https host: localhost basePath: /product

下面我们来看一个稍复杂一点的示例。

swagger: '2.0' info: version: '1.0' title: Swagger构建RESTful API host: 'localhost:8080' basePath: / tags: - name: product-controller description: Product Controller paths: /products: get: tags: - product-controller summary: 获取产品列表 description: 获取产品列表 operationId: getProductListUsingGET consumes: - application/json produces: - '*/*' responses: '200': description: OK schema: type: array items: $ref: '#/definitions/Product' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /products/{id}: get: tags: - product-controller summary: 获取产品详细信息 description: 根据URL的id来获取产品详细信息 operationId: getProductUsingGET consumes: - application/json produces: - '*/*' parameters: - name: id in: path description: 产品ID required: true type: integer responses: '200': description: OK schema: $ref: '#/definitions/Product' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found definitions: Product: type: object properties: count: type: integer format: int32 desc: type: string id: type: integer format: int32 name: type: string

上面的示例定义了两个API，一个是获取Product的列表，一个是根据id获取Product的详情。

编辑完成后，可以得到如图2-17所示的文档界面。