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

概述

 

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。

使用方法

插件的获取

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

插件的使用

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

    io.swagger
    huawei-swagger-codegen-maven-plugin
    2.2.2
    
        
            
                generate
            
        
    
    
        true
        
        generateAll
        
        
            ./yaml/swagger.yaml
        
        com.huawei.paas.cse.demo
        cse-test
        1.0.0
        
target/swagger
        yami
        2.1.35
        
        
        CSE-Java (JAX-RS)
    

说明：

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

    ./yaml/schema1.yaml
    ./yaml/schema2.yaml

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

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

CSE-Java (SpringMVC) SpringMVC开发模式

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

如：

CSE-Java (JAX-RS)

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路径，例如：

target/swagger

，代码会生成在当前项目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论坛进行咨询。