服务模块规范

服务模块概述

• 每个微服务应用中可以包含多个服务模块。
• 每个微服务应用的资源根目录是 model ，在 model/service 目录中包含了当前微服务应用的所有服务模块，服务模块目录不允许嵌套。

服务模块基本组成

服务目录标识文件 deploy.m

deploy.m 文件用于标识当前目录是服务模块目录，例如：model/service/app1/deploy.m 表示需要部署一个服务名为 app1 的服务，缺省的 deploy.m 文件是一个空文件。

服务网关注册文件 app.m

app.m 用于配置代理网关，每个 app.m 对应在网关上配置的一个接口.根据需要可以通过子目录创建多个 app.m 来实现在网关上配置多个接口，目录名不限，例如：

• model/service/{serviceName}/app.m
• model/service/{serviceName}/root/app.m
• model/service/{serviceName}/…/app.m

<?xml version="1.0" encoding="UTF-8" ?>
<service>
    <!-- 接口名 -->
    <name>davinci</name>
    <!-- 接口路由配置 -->
    <request_path>/davinci</request_path>
    <preserve_host>true</preserve_host>
    <strip_request_path>false</strip_request_path>
    <upstream_url>http://localhost:8787</upstream_url>
    <!-- 接口插件配置 -->
    <plugin name="authentication" enabled="false">
        <app_key>{{.Env.API_KEY}}</app_key>
        <app_secret>{{.Env.API_SECRET}}</app_secret>
    </plugin>
    <plugin name="health-check" enabled="true">
        <health_url>/davinci</health_url>
    </plugin>
</service>

服务定义文件 *.def.xml

服务在开发调试环境和部署运行环境下有不同的服务定义文件，分别对应架构设计工具中的开发架构和运行架构（kube或pool）。 一般服务环境定义文件有以下几个：

服务定义文件 *.def.xml 包含: properties 服务属性定义、uses 服务引用定义 和 spec 服务部署定义 三个部分。

<service>
  <!-- 服务属性定义 -->
  <properties>
    <property name="serviceAddress" value="${appsvc.serviceAddress}" readonly="true">
      <label label = "服务地址"/>
    </property>
    <property name="port" value="${appsvc.port}" readonly="true">
      <label label = "端口（port）"/>
        </property>
    <property name="dbType" value="${db.dbType}" readonly="true">
      <label label = "数据库类型"/>
    </property>
    <property name="dbHost" value="${db.dbHost}" readonly="true">
      <label label = "数据库服务地址"/>
    </property>
    <property name="dbPort" value="${db.dbPort}" readonly="true">
      <label label = "数据库端口"/>
    </property>
    <property name="dbUser" value="${db.dbUser}" readonly="true">
      <label label = "数据库用户名"/>
    </property>
    <property name="dbPasswd" value="${db.dbPasswd}" readonly="true">
      <label label = "数据库密码"/>
    </property>
    <property name="dbName" value="${db.dbName}" readonly="true">
      <label label = "数据库名称"/>
    </property>
    <property name="dbSchema" value="${db.dbSchema}" readonly="true">
      <label label = "dbSchema"/>
    </property>
    <property name="dbProperties" value="${db.dbProperties}" readonly="true">
      <label label = "dbProperties"/>
    </property>
    <property optional="true" name="dbextSharding" value="${db.dbextSharding}" readonly="true">
      <label label = "sharding"/>
    </property>
  </properties>
  <!-- 服务引用定义 -->
  <uses>
    <use name="db" instance="database"></use>
    <use name="minio" instance="minio"></use>
  </uses>
  <!-- 服务部署定义 -->
  <spec platform="app-container">
    <option name="name" value="appsvc" />
    <option name="instance" value="tomcat" />
  </spec>
</service>

服务属性定义 properties

服务属性使用 properties/property 定义，用于定义服务的配置属性和环境变量，例如: 地址、端口、用户名、密码、数据连接等。 每个 property 定义默认生成 ${serviceName}_${propertyName} 的环境变量（全大写，减号替换为下划线），可以在 property 上通过 env 属性控制环境变量的命名，env="-" 表示不产生环境变量。 说明：这里的环境变量就是服务运行时的环境变量，在 java 中可以通过 System.getenv 函数获取。

服务引用定义 uses

服务引用使用 uses/use 定义，用于定义服务之间的引用关系。 服务引用后，在服务的属性定义中就可以通过 ${serviceInstance.property} 引用其他服务的属性来配置当前服务的属性值.

可选服务引用和可选属性

在某些应用场景下，服务A对服务B的引用关系不是强制要求的，B是否存在，不影响A的正常运行，仅影响到A的执行逻辑。针对这种场景，服务定义允许定义可选的服务引用和属性。

<!-- 可选引用 -->
<uses>
  <use optional="true" name="dbproxy" instance="comp.dbproxy"></use>
</uses>

对于所有声明的可选服务引用 {name} ，有一个系统属性 @{name}Exists@ 用于获取目标服务是否存在的值, true/false。这个系统属性可用于定义引用端的property。

<!-- 可选属性 -->
<property name="dbproxyExists" value="@dbproxyExists@"  readonly="true">
  <label label = "dbproxy 是否存在"/>
</property>

应用运行时可读取 Exists 环境变量，根据环境变量的值分别处理目标服务存在和不存在的逻辑。 关于可选引用的 property，有以下特殊规则：

1. 通过可选引用引入的服务定义的 property，具备可选特性
2. 可选 property 具备传递性，一个 property 如果引用了可选 property，也具备可选特性，例如 A.a 引用了 B.b，如果 B.b 具备可选特性，那么 A.a 也具备可选特性
3. 具备可选特性的 property，如果服务不存在，该 property 在模型解析时被忽略，也不会生成环境变量。
4. 由于容器的 yaml 定义不具备条件判断的能力，所以具有可选特性的 property，不允许用于容器的yaml中。 除了上述4点外，其它特性与普通的 property 一致。

服务部署定义 spec

服务部署使用 spec 定义，用于定义服务的部署方式。

• <spec platform="docker-compose"/> 说明这是一个通过容器镜像部署的服务
• <spec platform="app-container"> 说明这是一个部署到运行容器的服务

服务部署定义的参数通过 option 子节点定义：

<!-- 容器镜像 -->
<spec platform="docker-compose" />

<!-- Java Tomcat -->
<spec platform="app-container">
  <option name="name" value="appsvc" />
  <option name="instance" value="tomcat" />
  <option name="container" value="java" />
  <option name="deploy" value="true" />
</spec>

<!-- Nginx -->
<spec platform="app-container">
  <option name="name" value="appsvc" />
  <option name="instance" value="nginx-runtime" />
  <option name="container" value="nginx" />
  <option name="deploy" value="true" />
</spec>

<!-- Java Spring Boot -->
<spec platform="app-container">
  <option name="name" value="appsvc" />
  <option name="instance" value="java-runtime" />
  <option name="container" value="java" />
  <option name="deploy" value="true" />
</spec>

自定义脚本文件与服务模块的运行生命周期

服务模块可以看成是一个标准服务，有初始化、启动、停止。初始化属于部署后需要执行的逻辑，在新部署、升级部署、关联模版变更时候执行；启动和停止是在每次池绑定或者解绑时执行。

服务模块的运行生命周期包含以下几个阶段：

对于用户自定义的服务模块，可以通过自定义脚本文件，在相应的服务运行阶段执行 shell 脚本。自定义脚本文件的命名规范：

• 文件路径：model/service/{serviceName}/deploy/*.sh 。
• 默认文件名：${阶段}.sh，install.sh，init0.sh，start.sh，init.sh，inited.sh, stop.sh 。
• 按部署类型区分：${部署类型}.${阶段}.sh，部署类型的取值范围：dev、production、kube.production、pool.production，例如：如果对于 kube 和 pool 的生产部署需要有不同的 start 脚本，可以分别定义 kube.production.start.sh 和 pool.production.start.sh 。