# Java Chassis接入CSE
本章节介绍Java Chassis如何接入CSE，使得Java Chassis能够对接CSE，并且方便地使用CSE提供的最常用的功能。在[使用微服务引擎功能](https://support.huaweicloud.com/devg-servicestage/cse_04_0012.html)章节，会给出具体的开发指导。
本章节介绍的开发方法，可以在[Apache ServiceComb Samples](https://github.com/apache/servicecomb-samples/tree/master/basic)项目中找到对应的代码，供您在开发过程中参考。
#### 前提条件
- 已基于Java Chassis开发好了微服务应用。 Java Chassis框架下的微服务应用开发，请参考。
- 版本要求：请参见[微服务开发框架版本要求](https://support.huaweicloud.com/devg-servicestage/cse_04_0005.html#cse_04_0005__section56161456192411)。
- 本文假设您的项目使用了maven管理打包，您熟悉maven的依赖管理机制，能够正确地修改"pom.xml"文件中的dependency management和dependency。
- Java Chassis支持和不同的技术进行组合使用，配置文件的名称和实际使用的技术有关。如果您采用Spring方式使用Java Chassis，配置文件的名称一般为"microservice.yaml"，如果您采用Spring Boot方式使用Java Chassis， 配置文件名称一般为"application.yaml"。本文统一使用"microservice.yaml"表示配置文件，请结合实际项目进行区分。
#### 操作步骤
1. 在项目的"pom.xml"文件中引入依赖。
```
org.apache.servicecomb
solution-basic
org.apache.servicecomb
servicestage-environment
```
- 上述模块solution-basic包含常用的Java Chassis功能，例如配置中心模块和服务治理模块，方便一键式启用Java Chassis常见功能。
```
org.apache.servicecomb
config-cc
org.apache.servicecomb
handler-governance
```
- 上述模块servicestage-environment包含以下依赖模块：
```
org.apache.servicecomb
registry-service-center
```
推荐使用Maven Dependency Management管理项目依赖的三方软件，在项目的"pom.xml"文件中引入：
```
org.apache.servicecomb
java-chassis-dependencies
${java-chassis.version}
pom
import
```
如果您的项目中，已经包含了上述依赖，则不需要做任何处理。
其中servicestage-environment软件包是可选的。这个软件包提供了环境变量映射的功能，依赖这个软件包以后，当您采用ServiceStage部署应用，不用手工修改注册中心地址、配置中心地址、项目名称等信息，会通过环境变量覆盖"microservice.yaml"中的默认配置，它包含"mapping.yaml"文件，在您自己的项目中增加"mapping.yaml"文件能够起到同样的效果。
"mapping.yaml"在后续新版本可能会发生变化，以适配CSE最新的功能要求。如果期望后续升级新版本保持稳定而不是跟随CSE演进，您可以选择不依赖servicestage-environment，而是在您自己的项目中增加"mapping.yaml"。
"microservice.yaml"和"mapping.yaml"文件，一般都存放于您当前项目根目录下的"/src/main/resources/"路径下。
```
PAAS_CSE_ENDPOINT:
- servicecomb.service.registry.address
- servicecomb.config.client.serverUri
PAAS_CSE_SC_ENDPOINT:
- servicecomb.service.registry.address
PAAS_CSE_CC_ENDPOINT:
- servicecomb.config.client.serverUri
PAAS_PROJECT_NAME:
- servicecomb.credentials.project
# CAS_APPLICATION_NAME:
# - servicecomb.service.application
# CAS_COMPONENT_NAME:
# - servicecomb.service.name
# CAS_INSTANCE_VERSION:
# - servicecomb.service.version
```
solution-basic里面引入了常用的软件包，并且提供了默认的"microservice.yaml"文件。这个配置文件配置了常用的Handler和参数。其内容如下：
```
# order of this configure file
servicecomb-config-order: -100
servicecomb:
# handlers
handler:
chain:
Provider:
default: qps-flowcontrol-provider
Consumer:
default: qps-flowcontrol-consumer,loadbalance,fault-injection-consumer
# loadbalance strategies
references:
version-rule: 0+
loadbalance:
retryEnabled: true
retryOnNext: 1
retryOnSame: 0
# metrics and access log
accesslog:
enabled: true
metrics:
window_time: 60000
invocation:
latencyDistribution: 0,1,10,100,1000
Consumer.invocation.slow:
enabled: true
msTime: 1000
Provider.invocation.slow:
enabled: true
msTime: 1000
publisher.defaultLog:
enabled: true
endpoints.client.detail.enabled: true
```
"microservice.yaml"配置文件设置了servicecomb-config-order: -100 ， 表示配置文件的优先级很低（order越大，优先级越高，缺省为0），如果业务服务增加了同样的配置项，会覆盖这里的配置。
"microservice.yaml"文件在后续新版本可能会发生变化，以适配CSE最新的功能要求。如果期望后续升级新版本保持稳定而不是跟随CSE演进，您可以考虑将配置项写到您自己的"microservice.yaml"文件中。
2. 配置微服务信息。
在"microservice.yaml"增加微服务配置描述信息。如果项目中没有"microservice.yaml"，则创建一个新的文件。
```
servicecomb:
service:
application: porter-application
name: user-service
version: 0.0.1
registry:
address: http://localhost:30100
instance:
watch: true
properties:
key: value
initialStatus: UP
config:
client:
serverUri: http://localhost:30103
fileSource: provider.yaml
firstPullRequired: false
refresh_interval: 15000
domainName: default
kie:
serverUri: http://127.0.0.1:30110
domainName: default
enableLongPolling: true
pollingWaitTime: 10
firstPullRequired: false
customLabel: public
customLabelValue: default
```
其中，各个配置项说明见[表1]。
表1Java Chassis配置项
| 配置项 | 含义 | 缺省值 | 是否必须配置 | 备注 |
|:---|:---|:---|:---|:---|
| servicecomb.service.application | 为当前微服务所属应用名称。 | default | 是 | 应用名称相同的微服务之间才可以相互发现。 |
| servicecomb.service.name | 为当前微服务名称。 | - | 是 | - |
| servicecomb.service.version | 服务版本号。 | 1.0.0.0 | 是 | 服务升级的时需要，防止契约注册失败。 |
| servicecomb.service.registry.address | 注册地址。 | - | 是 | - |
| servicecomb.service.registry.instance.watch | 是否侦听微服务上下线变化。 | true | 否 | 集群地址使用","分隔。 |
| servicecomb.service.registry.instance.properties | 微服务实例属性。 | - | 否 | 为map结构，支持设置多组数据。 |
| servicecomb.service.registry.instance.initialStatus | 微服务注册时的状态。 | UP | 否 | 可设置UP(上线)、DOWN(下线)。 |
| servicecomb.config.client.serverUri | 访问地址，格式为http(s)://{ip}:{port}，以","分隔多个地址。 | - | 是 | 此配置适用于配置中心为config-center。 - 当微服务引擎版本为1.x时，{*port*}取值为30103。 - 当微服务引擎版本为2.x时，{*port*}取值为30110。 |
| servicecomb.config.client.fileSource | 内容为yaml的配置项列表，使用","分隔。 | - | 否 | 当配置中心类型为config-center时，如果配置中心以配置文件形式下发配置，必须填写fileSource予以解析配置，否则无法获取正确的配置内容。 |
| servicecomb.config.client.firstPullRequired | 第一次拉取配置是否强制要求成功。如果为true，那么第一次连接配置中心失败后直接抛出异常，服务启动失败。默认为false。 | - | 否 | 此配置适用于配置中心为config-center。 |
| servicecomb.config.client.refresh_interval | 配置中心config-center拉取配置循环时间，单位为毫秒。 | 15000 | 否 | 此配置适用于配置中心为config-center。 |
| servicecomb.config.client.domainName | 项目名称。 | default | 否 | 此配置适用于配置中心为config-center。 |
| servicecomb.kie.serverUri | 访问地址，格式为http(s)://{ip}:{port}，以","分隔多个地址。 | - | 是 | 此配置适用于配置中心为kie。 - 当微服务引擎版本为1.x时，{*port*}取值为30103。 - 当微服务引擎版本为2.x时，{*port*}取值为30110。 |
| servicecomb.kie.domainName | 项目名称。 | - | 否 | 此配置适用于配置中心为kie。 |
| servicecomb.kie.enableLongPolling | 是否开启长连接拉取配置。 | true | 否 | 此配置适用于配置中心为kie。 |
| servicecomb.kie.pollingWaitTime | 长连接等待时长，单位为秒。 | 10 | 否 | 此配置适用于配置中心为kie。 |
| servicecomb.kie.firstPullRequired | 第一次拉取配置是否强制要求成功。如果为true，那么第一次连接配置中心失败后直接抛出异常，服务启动失败。默认为false。 | - | 否 | 此配置适用于配置中心为kie。 |
| servicecomb.kie.customLabel | 自定义配置标签键值。 | - | 否 | 使用kie配置中心时，如果使用自定义标签方式下发配置，需要配置customLabel、customLabelValue，微服务名、环境名、应用名标签仅支持单独适配。 |
| servicecomb.kie.customLabelValue | 为自定义配置标签值 | - | 否 | - |
3. （可选）配置AK/SK。
如果使用微服务引擎专业版，需要配置AK/SK，请参考[为接入专业版微服务引擎的Java Chassis微服务应用配置AK/SK](https://support.huaweicloud.com/devg-servicestage/cse_04_0041.html)。
如果使用微服务引擎专享版，不需要配置AK/SK，可以跳过这个步骤。
- 使用环境变量。操作系统环境变量名称不支持"."，Java Chassis能够自动处理servicecomb_credentials_accessKey环境变量，将其映射到servicecomb.credentials.accessKey。
- 增加"mapping.yaml"文件，自定义环境变量名称。在[1]介绍模块servicestage-environment的时候，已经用到了这个方法。
4. （可选）配置安全认证参数。
使用微服务引擎专享版，并且启用了安全认证，需要配置，其他场景可以跳过这个步骤。
微服务引擎开启了安全认证之后，所有调用的API都需要先获取token，才能调用，认证流程请参考[服务中心RBAC说明](https://service-center.readthedocs.io/en/latest/user-guides/rbac.html)。
使用安全认证首先需要从微服务引擎获取用户名和密码，然后在配置文件中增加如下配置：
```
servicecomb:
credentials:
rbac.enabled: true
account:
name: your account name # 从微服务引擎获取的用户名
password: your password # 从微服务引擎获取的密码
cipher: default #接口org.apache.servicecomb.foundation.auth.Cipher的实现类里面的name()方法返回的名称
```
其中"cipher"指定了对"password"进行加密的算法名称，默认提供明文存储。通过自定义实现加密，如下所示：
- 自定义实现，首先实现接口"org.apache.servicecomb.foundation.auth.Cipher"，里面的两个方法：
- String name() 这个是servicecomb.credentials.cipher的名称定义，需要配置在配置文件中。
- char\[\] decode(char\[\] encrypted) 解密接口，对secretKey进行解密后使用。
实现类需要声明为SPI，比如：
```
package com.example
public class MyCipher implements Cipher
```
创建SPI配置文件，文件名称和路径为META-INF/service/org.apache.servicecomb.foundation.auth.Cipher， 文件内容为：
```
com.example.MyCipher
```
然后在"microservice.yaml"文件中增加配置。
```
servicecomb:
credentials:
rbac.enabled: true
account:
name: your account name
password: your password # 加密后的密码
cipher: youciphername #实现类里面的name()方法返回的名称
```
- 明文存储无法保证安全， 建议您对密码进行加密存储。
- 和配置AK/SK一样，也可以使用环境变量配置用户名和密码信息，请参考[为接入专业版微服务引擎的Java Chassis微服务应用配置AK/SK](https://support.huaweicloud.com/devg-servicestage/cse_04_0041.html)。
- 使用微服务引擎专业版，不能使用watch功能，需要在配置文件里面关闭，否则会周期性打印错误日志。服务中心设置watch=false，配置中心设置refreshMode=1。
```
servicecomb:
service:
application: porter-application
name: user-service
version: 0.0.1
registry:
address: http://localhost:30100
instance:
watch: false
config:
client:
serverUri: http://localhost:30103
refreshMode: 1
```