微服务开发规范模版

1 二方组件分发与使用规范

1.1 二方组件的特征

1. JAR、JS、DLL、SO、LIB 等动态或静态库

1. 源码由团队自己管控（完全自研或对三方代码定制化修改）

1. 组件已放在统一的组件仓库（Nexus）中

1.2 二方组件的提供

1. 各组架构负责人都可以提出用组件的方式用作与外部系统的集成（须集成方案获准）

1. 提供的二方组件源码必须置于统一的源码仓库管理

1. 提供方须保证对二方组件的持续维护

1. 正式发布的二方组件需要有配套的文档输出，以指导使用方集成

1.3 二方组件的发布

1. 二方组件发布前必须在源码仓库上建立对应的 Tag

1. 二方组件发布的版本号需满足配置管理规范定义

1. 后端的组件基于 Maven 分发时，允许在版本还不稳定的时候使用 SNAPSHOT 的方式发布到仓库

1.4 二方组件的引用原则

1. 使用方必须使用正式版本的二方组件

1.5 二方 Maven 组件的引用细则

1. release 和 master 分支的代码不允许使用 SNAPSHOT 的二方组件

1. 优先使用 common-parent 统一管理二方组件的引用版本

1.6 二方 NPM 组件的引用细则

• 前端组件通过 NPM 私服进行引用管理，规则同 Maven 组件策略

---

2 K8S 内资源命名规范

2.1 常用资源类型

|-----------------------|------------------------|------------|------------|
| KIND | NAME | SHORTNAMES | NAMESPACED |
| ConfigMap | configmaps | cm | TRUE |
| DaemonSet | daemonsets | ds | TRUE |
| Deployment | deployments | deploy | TRUE |
| Ingress | ingresses | ing | TRUE |
| Job | jobs | --- | TRUE |
| Namespace | namespaces | ns | FALSE |
| PersistentVolumeClaim | persistentvolumeclaims | pvc | TRUE |
| PersistentVolume | persistentvolumes | pv | FALSE |
| Pod | pods | po | TRUE |
| Secret | secrets | --- | TRUE |
| Service | services | svc | TRUE |

2.2 模块名说明

模块名作为各资源的标识基本组成部分，取值参考云原生软件模块清单。

2.3 Namespace 命名

规范： namespace-name := 环境大类-环境小类

|------|-----------------|---------------------|
| 环境分组 | NameSpace | 说明 |
| DEV | dev | 开发环境 |
| DEV | sit-dev-api | 开发-SIT API |
| SIT | sit-api-release | SIT API（release 分支） |
| SIT | sit-ui-release | SIT UI（release 分支） |
| UAT | uat-api-release | UAT API（release 分支） |
| UAT | uat-ui-release | UAT UI（release 分支） |
| UAT | uat-api-master | UAT API（master 分支） |
| UAT | uat-ui-master | UAT UI（master 分支） |
| PET | stress | 压测环境 |

2.4 各资源命名规则

Deployment<Module Name>-特殊后缀-deploy

|------------------------------|--------|
| 示例 | 备注 |
| app-auth-server-deploy | 前台认证 |
| app-auth-server-admin-deploy | 管理后台认证 |

Service<Module Name>-特殊后缀-svc

|---------------------------|--------|
| 示例 | 备注 |
| app-auth-server-svc | 前台认证 |
| app-auth-server-admin-svc | 管理后台认证 |

ConfigMap<Module Name>-特殊后缀-cm

示例：app-auth-server-cm

Ingress<Module Name>-特殊后缀-ing

示例：app-auth-server-ing

Secret<Module Name>-特殊后缀-secret

示例：app-auth-server-secret

---

3 代码仓库目录结构规范

3.1 说明

该规范用于约束所有需要 CI/CD 流程的产品代码仓库。

3.2 仓库目录结构

单个代码仓库的目录结构如下：

产品名.git

├── devops/ # 工程部署和配置相关文件

├── xxx-backend/ # 后端工程

├── web/ # 前端工程

├── tc/ # 测试相关代码及脚本

├── lib-sdk/ # 多语言 SDK 工程

├── 独立服务/ # 与主工程无直接关联的服务

└── README.md # 仓库结构和工程说明

3.3 DevOps 目录结构

devops/

├── deploy/

│ ├── helm/

│ │ ├── xxx/

│ │ │ ├── templates/

│ │ │ ├── charts/

│ │ │ │ └── web-svc/ # 多模块

│ │ │ │ ├── templates/

│ │ │ │ │ ├── cm.yaml # 可选

│ │ │ │ │ ├── deploy.yaml

│ │ │ │ │ ├── svc.yaml

│ │ │ │ │ └── ing.yaml # 可选

│ │ │ │ ├── Chart.yaml

│ │ │ │ └── values.yaml

│ │ │ ├── Chart.yaml

│ │ │ ├── README.md

│ │ │ └── values.yaml

│ │ └── values/

│ │ └── values-{namespace}.yaml

├── jenkins/

│ └── {namespace}-xxx.groovy

└── nacos/

└── {namespace}/

└── xxx.{yml/properties}

3.4 前端目录结构

web/

└── xxx-web/

├── config/

├── mock/

├── plugin/

├── public/

├── src/

└── test/

3.5 后端目录结构

xxx/

├── xxx/ # 单个服务 module

│ ├── src/

│ ├── Dockerfile

│ └── pom.xml

└── xxx-{interface/facade}/ # 基于 SDK 包

├── src/

│ ├── {package}.feign # Feign 调用接口

│ └── {package}.model # 调用依赖对象

└── pom.xml

3.6 SDK 目录结构

lib-sdk/

└── xxx/

└── {language}/

├── xxx-{language}/ # SDK 包

└── xxx-{language}-demo/ # 调用示例

SDK 按功能按开发语言进行区分，同时提供调用 demo 参考。

---

4 镜像仓库管理规范

4.1 仓库地址及功能

|-----------------|-------------------------|
| 功能 | 地址 |
| dev | registry-dev（开发环境） |
| sit/uat/preprod | registry-sit（测试/验收/预生产） |
| 生产 | registry（生产环境） |

登录方式：域账号用户名 / 密码

4.2 项目命名及功能

|-------------|----------------|
| 项目名称 | 功能 |
| base | 存放基础镜像 |
| app-uap | 存放 UAP 项目镜像 |
| app-uclass | 存放 UCLASS 项目镜像 |
| app-solar | 存放 SOLAR 项目镜像 |
| app-monitor | 存放监控平台项目镜像 |

4.3 Helm Chart 管理

|-----|--------------|-----------------|-----|
| 团队 | Project Name | Repository Name | 备注 |
| POC | charts | uap | --- |
| POC | charts | solar | --- |
| POC | charts | uclass | --- |
| POC | charts | cgs | --- |
| POC | charts | monitor | --- |

4.4 镜像命名规则

镜像地址路径规则：镜像地址 = registry/repository:tag

|------------|--------------------------------------------------------|
| 分支类型 | Tag 格式 |
| develop 镜像 | registry/repository:latest |
| release 镜像 | registry/repository:release-build_num-date |
| master 镜像 | registry/repository:stable-build_num-date |
| tag 镜像 | registry/repository:R001.0.0.000001-20200515-build_num |

4.5 Chart 命名规范

Chart 包命名规则：产品名-环境名-用途

apiVersion: v1

appVersion: M2.1

name: app

version: x.y.z

description: A helm chart for application in Kubernetes cluster

release 版本时需要同步修改 Chart 版本号和应用版本号。

4.6 镜像使用命令

# 登录仓库

docker login registry

# 镜像拉取

docker pull registry/repository:tag

# 镜像推送

docker push registry/repository:tag

# 镜像重命名

docker tag IMAGEID REPOSITORY:TAG

---

5 Dockerfile 规范

5.1 基本必填字段

|------------|---------|----|-----|
| 属性 | 描述 | 必填 | 备注 |
| FROM | 指定基础镜像 | 是 | --- |
| MAINTAINER | 维护者信息 | 是 | --- |
| ENV | 传递环境变量 | 是 | --- |
| ARG | 传递构建变量 | 是 | --- |
| WORKDIR | 切换到指定目录 | 是 | --- |
| ADD | 拷贝文件到容器 | 是 | --- |
| EXPOSE | 指定交互端口 | 是 | --- |
| CMD | 容器启动命令 | 是 | --- |

5.2 示例

# 基础镜像

FROM registry-dev/base/openjdk:v1

# 维护者信息

MAINTAINER devops-team

# 传入 JAVA_OPTS 变量，用于限制 JVM 内存大小，通过 Helm values 统一配置

ENV JAVA_OPTS="-Xmx512M -Xms512M"

# 指定传递给构建运行时的变量 workdir

ARG workdir=/home/

# 进入到 home 目录

WORKDIR ${workdir}

# 将本地 jar 包拷贝到容器中

ADD app.jar app.jar

# 指定应用启动的交互端口

EXPOSE 8086

# 容器启动运行的命令

CMD ["sh","-c","java $JAVA_OPTS -jar app.jar"]

---

6 基础镜像定制流程

6.1 基本流程

由各 Team 架构和能力中心代表提出需求给 POC 团队，然后由 POC 统一定制基础镜像。

6.2 需求模板

基础镜像内容包括：

• a. OS 操作系统

• b. ENV 环境变量

• c. 操作系统基础资源（如字体文件）

• d. App-runtime（应用运行时）

• e. App-Jar（应用包）

• f. 辅助工具（curl、tcpdump 等）

• 提出方需明确以上需求项

---

7 Java 包名与类名规范

7.1 顶级包名

com.app.framework

7.2 子包定义

规则为 com.app.framework.{app}.{module}，app 代表各个服务名，module 代表服务内的模块。

com.app.framework.ris.papr // app=ris, module=papr

com.app.framework.ris.report // app=ris, module=report

7.3 Spring MVC Controller 层

包名规范

内部调用 API（给内部产品调用，如前端调用）

规则：com.app.framework.{app}.{module}.controller.{version}

com.app.framework.ris.papr.controller.v1

com.app.framework.ris.papr.controller.v2

URL 映射：/{version}/{controllerName}示例：/v1/patients

外部调用 API（给第三方调用）

规则：com.app.framework.{app}.{module}.api.controller.{version}

com.app.framework.ris.papr.api.controller.v1

com.app.framework.ris.papr.api.controller.v2

URL 映射：/{version}/api/{controllerName}示例：/v1/api/patients

类名规范

Controller 类以 Controller 结尾，继承 common 库中的 BaseController。

7.4 Mybatis Mapper 层

• 包名： com.app.framework.{app}.{module}.mapper

• 类名： 以 Mapper 结尾，继承 common 库的 BaseMapper 接口

com.app.framework.ris.papr.mapper.PatientMapper

7.5 Service 层

• 接口包名： com.app.framework.{app}.{module}.service

• 实现包名： com.app.framework.{app}.{module}.service.impl

• 接口名： 以 Service 结尾，继承 BaseService 接口

• 实现类名： 以 ServiceImpl 结尾，继承 BaseServiceImpl 类

com.app.framework.ris.papr.service.PatientService // 接口

com.app.framework.ris.papr.service.impl.PatientServiceImpl // 实现

7.6 实体映射层

• 包名： com.app.framework.{app}.{module}.entity

7.7 Model 层

Model 层为 VO（View Object）或 DTO（Data Transfer Object）提供统一包名。

• 包名： com.app.framework.{app}.{module}.Model

7.8 工具类

• 尽量使用 common 库中的工具类

• 项目特定的工具类包名：com.app.framework.{app}.{module}.util

以上所有规范中的 app 名称、module 名称均为示例，实际使用时替换为具体项目名称。包名中的顶级域名可根据实际组织架构调整。