概述

CSE提供了一套工具和插件，让用户更加方便的开发功能。包括：

契约开发工具。更好的编辑契约。
代码生成插件。通过契约生成代码。
加密工具。保护AK/SK，进行数据加密存储等。

契约开发工具

概念阐述

本节介绍的契约开发工具是Swagger。

Swagger介绍

Swagger是一种和语言无关的规范和框架，是一个API设计工具，用于定义服务接口，主要用于描述RESTful的API。它专注于为API创建优秀的文档和客户端库。

Swagger包括库、编辑器、代码生成器等很多部分，在Java Chassis框架中已经集成了Swagger库，同时在ServiceStage中提供了在线契约编辑的功能，这里主要介绍Swagger以下内容：

Swagger API Spec，描述Rest API的语言。
ServiceStage Swagger API Editor，ServiceStage上提供的Swagger API Spec的编辑器。

Swagger API Spec

Swagger API Spec是Swagger用来描述Rest API的语言，可以使用yaml或json来表示。Swagger API Spec包含以下部分：

swagger，指定swagger spec版本，2.0
info，提供API的元数据
basePath，相对于host的路径
schemes，API的传输协议，http，https，ws，wss
consumes，API可以消费的MIME类型列表
produces，API产生的MIME类型列表
paths，API的路径，以及每个路径的HTTP方法，一个路径加上一个HTTP方法构成了一个操作。每个操作都有以下内容：
- tags，操作的标签
- description，描述
- externalDocs，外部文档
- operationId，标识操作的唯一字符串
- consumes，MIME类型列表
- produces，MIME类型列表
- parameters，参数列表，参数的描述包括：
  - name，名字
  - description，描述required，是否必须
  - in，参数获取的位置，包括如下几种：
    - Path、Query、Header、Body、Form
    - （对于Body类型的参数）
      - schema，数据类型，可以详细描述，也可以引用definition部分定义的schema
    - （对于Body类型以外的参数）
      - type，类型
      - format，数据格式
      - allowEmptyValue，是否允许空值
      - items，对于Array类型
      - collectionFormat，对于Array类型
      - default，缺省值
- responses，应答状态码和对于的消息的Schema
- schemes，传输协议
- deprecated，不推荐使用
- security，安全
definitions，定义API消费或生产的数据类型，使用json-schema描述，操作的parameter和response部分可以通过引用的方式使用definitions部分定义的schema

Swagger API Spec对Rest API的每一个操作的请求消息的参数（Path,Query,Body,Form），响应消息的状态码和消息体的json结构都进行了详细的描述。如果需要查看详细的Swagger API Spec定义，请参考http://swagger.io/specification/。

ServiceStage API Editor

ServiceStage提供了在线的Swagger API Editor，链接是ServiceStage API Editor，需要事先注册和登录华为云账号。

ServiceStage API Editor是Swagger API Spec的编辑器，Swagger API Spec支持两种文件格式，yaml和json，在ServiceStage API Editor中使用yaml或者json格式中进行编辑，同时允许下载两种格式的文件。在yaml编辑器的右面有所见即所得的预览。华为云微服务工具和插件介绍

ServiceStage API Editor页面的文件菜单提供了以下功能：

File，文档下载

Download YAML，下载yaml格式的契约文件。

Download JSON，下载json格式的契约文件。

Edit

Convert to YAML，将json格式的契约定义转换成yaml格式。

Generate-Document

HTML，生成描述api的html文档。

代码生成插件

概念阐述

本节介绍如何在Maven插件方式下使用CSE-Codegen。

使用方法

插件的获取

进入微服务引擎页面。
在“微服务开发 > 工具下载”页面获取CSE-SDK JAVA的依赖包，然后解压到本地Maven库中。

插件的使用

首先准备好一个API spec文件，该文件可以是json格式，或yaml格式，然后在pom.xml中增加插件配置，如下：

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>huawei-swagger-codegen-maven-plugin</artifactId>
    <version>2.2.2</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <skipOverwrite>true</skipOverwrite>
        <!-- generateAll or generateInterface -->
        <generateLevel>generateAll</generateLevel>
        <!-- specify the swagger yaml -->
        <inputSpecs>
            <param>./yaml/swagger.yaml</param>
        </inputSpecs>
        <groupId>com.huawei.paas.cse.demo</groupId>
        <artifactId>cse-test</artifactId>
        <artifactVersion>1.0.0</artifactVersion>
        <output>target/swagger</output>
        <serviceName>yami</serviceName>
        <cseVersion>2.1.35</cseVersion>
        <!-- target to generate -->
        <!--CSE-Java (JAX-RS)  | CSE-Java (SpringMVC) | CSE-Java (POJO) -->
        <language>CSE-Java (JAX-RS)</language>
    </configuration>
</plugin>

说明：

1、其中inputSpecs表示输入的spec api文件，可使用相对路径，支持多schema文件，文件名将作为本契约的schemaId，如

</inputSpecs>
    <param>./yaml/schema1.yaml</param>
    <param>./yaml/schema2.yaml</param>
</inputSpecs>

2、language指定生成目标目标代码类型，生成不同的开发模式，当前支持的目标代码类型有：

CSE-Java (JAX-RS) JAX-RS开发模式

CSE-Java (SpringMVC) SpringMVC开发模式

CSE-Java (POJO) 透明RPC开发模式

如：

3、output表示输出路径

4、skipOverwrite表示是否覆盖已经存在的文件

5、generateLevel表示生成的形式，支持两种generateAll 和generateInterface，generateAll表示生成全量工程，generateInterface表示只生成接口定义文件，例如SpringMVC模式，只生成RequestMapping文件。通常最开始的时候需要生成全量工程，后面开发过程中，新增加一个契约文件时，只需要生成接口即可。

6、serviceName 微服务名称，体现在microservice.yaml文件里面。

7、cseVersion CSE微服务版本号。

8、groupId artifactId artifactVersion，这三个参数均对应maven工程的坐标。

执行以下命令：

mvn generate-sources

根据配置的output路径，例如：<output>target/swagger</output>，代码会生成在当前项目target/swagger目录下。

加密工具

概念阐述

本节介绍的AK/SK加密存储是基于共享秘钥的AES256加解密存储方案，通过工具生成秘钥物料，然后使用工具利用秘钥文件对指定的明文进行加密。例如可以使用这种方法对数据库密码进行加密，使用的时候再使用CSE SDK接口进行解密。

AK/SK存储方案

AK/SK认证依赖用户配置的AK/SK，CSE默认支持自定义配置，用户可以自己实现解密接口，也可以使用CSE默认提供的机制。CSE内部默认提供明文和安全两种实现机制，下面分别来介绍下三种方式的配置方法。

1、明文方法，在microservice.yaml文件中增加配置

  cse:  
    credentials:
    accessKey: yourak
    secretKey: yoursk
    akskCustomCipher: default

2、密文方式，在microservice.yaml文件中增加配置

cse:
  credentials:
    accessKey: yourak  #明文
    secretKey: yoursk  #密文
    akskCustomCipher: security

默认提供的安全存储中，ak是不进行加密的。读取cipher的时候，会优先读取CIPHER_ROOT下面的certificate.yaml配置，参考AK/SK安全存储详细操作步骤

3、自定义实现，首先自己实现一个接口com.huawei.paas.foundation.auth.credentials.AKSKCipher，里面有两个方法：

String name();

这个是解密实现的名称定义，需要配置在配置文件中

char[] decode(TYPE type, char[] encrypted);

解密接口，TYPE表示ak还是sk，因为两者可能实现不一样的加密方式。

在microservice.yaml文件中增加配置

cse:
  credentials:
    accessKey: yourak  #对应的加解密后的ak
    secretKey: yoursk  #对应的加解密后的sk
    akskCustomCipher: youciphername  #实现类里面的name()方法返回的名称

再添加接口的SPI声明，在src/main/resources/META-INF/services新建一个文件com.huawei.paas.foundation.auth.credentials.AKSKCipher，内容为自己的实现类类名，例如：com.huawei.paas.cse.demo.pojo.client.CustomAKSKDepl

AK/SK安全存储详细操作步骤

1、下载加解密工具，提供windowns和linux两个版本

2、使用加解密工具生成物料，使用命令keytool gen -a yourak -s yoursk命令，会在当前目录下生成root.key、common_shared.key，和certificate.yaml文件，详细说明可以查看工具的帮助keytool gen -h

3、拷贝root.key、common_shared.key、certificate.yaml到环境中，建议放到/opt/CSE/etc/cipher，本地调试的时候可以放到任意目录，所有需要部署微服务的节点都需要。如果是容器化部署，还需要挂载卷到指定目录。

4、启动应用，在启动应用之前需要先设置一个环境变量CIPHER_ROOT，就是第四步复制凭证文件所在的目录

5、查看CSE控制台面板，服务是否注册成功，也可以查看应用启动日志，是否有服务注册成功日志。

了解更多

开发者可以通过微服务引擎华为云官网了解CSE。在CSE帮助中心可以获取更多产品信息，如有疑问，可通过CSE论坛进行咨询。

华为云微服务工具和插件介绍

概述

契约开发工具

概念阐述

Swagger介绍

Swagger API Spec

ServiceStage API Editor

代码生成插件

概念阐述

使用方法

插件的获取

插件的使用

加密工具

概念阐述

AK/SK存储方案

AK/SK安全存储详细操作步骤

了解更多

相关推荐