v6ole
508 lines
9.4 KiB
Markdown
508 lines
9.4 KiB
Markdown
# 研发云互联互通规范服务接入技术规范（脚手架服务）（试行稿）
|
|
|
|
> 脱敏整理版：已移除编制人员、联系人和联系方式，并合并无意义硬换行。技术条款、章节和示例以原始 DOCX 为争议核验依据。
|
|
|
|
研发云互联互通规范
|
|
|
|
服务接入技术规范（脚手架服务）
|
|
|
|
中国电信股份有限公司研究院研发云平台运营中心
|
|
|
|
## 2025 年 5 月
|
|
|
|
1
|
|
|
|
> 编制人员信息已移除。
|
|
|
|
版本变更历史
|
|
|
|
3
|
|
|
|
## 1 文档说明
|
|
|
|
### 1.1 编制说明
|
|
|
|
本规范服务对象为中国电信集团及下属各级单位
|
|
|
|
### 1.2 适用范围
|
|
|
|
中国电信集团范围内
|
|
|
|
### 1.3 起草单位
|
|
|
|
中国电信股份有限公司研究院-研发云平台运营中心
|
|
|
|
### 1.4 解释权
|
|
|
|
中国电信股份有限公司研究院-研发云平台运营中心
|
|
|
|
### 1.5 版权
|
|
|
|
中国电信股份有限公司研究院-研发云平台运营中心
|
|
|
|
### 1.6 名词解释
|
|
|
|
1
|
|
|
|
## 2 概述
|
|
|
|
合作单位通过标准化方式将自己单位开发的服务快速接入研发云平台，拓展研发云平台功能，以满足更多业务场景。目前支持的主要内容是脚手架服务接入。研发云代码中心支持从模板创建代码仓库，即调用脚手架服务快速灵活的生成各类搭配的项目初始化代码库。
|
|
|
|
## 3 脚手架接入
|
|
|
|
### 3.1 集成开发规范
|
|
|
|
脚手架工具开发需符合研发云数据结构规范、签名认证规范，如有不满足，双方协商修改。
|
|
|
|
#### 3.1.1 数据结构规范
|
|
|
|
● 数据流向：脚手架服务-->研发云● 数据结构说明：由脚手架服务向研发云平台提供脚手架服务可对接使用的模板信息、组件信息等。
|
|
|
|
Scaffold 数据结构定义：
|
|
|
|
2
|
|
|
|
3
|
|
|
|
Component 数据结构定义：
|
|
|
|
● 示例：4
|
|
|
|
{
|
|
|
|
"scaffolds": [
|
|
|
|
{
|
|
|
|
"templateId": "9340db83-5186-4d5b-aa98-bb0d8f99274b", "templateName": "基础 Web 应用",
|
|
|
|
"version": "1.0.0",
|
|
|
|
"description": "这是一个基础的 Web 应用脚手架",
|
|
|
|
"language": "Java",
|
|
|
|
"buildType": "Maven",
|
|
|
|
"components": [
|
|
|
|
{
|
|
|
|
"componentId": "e543562b-b59c-4d32-b86c-183113c56159", "componentName": "MySQL 数据库连接",
|
|
|
|
"description": "用于连接 MySQL 数据库的组件",
|
|
|
|
"type": "database",
|
|
|
|
"version": "1.0"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"componentId": "e543562b-b59c-4d32-b86c-183113c56159", "componentName": "JWT 认证",
|
|
|
|
"description": "基于 JWT 的认证安全组件",
|
|
|
|
"type": "security",
|
|
|
|
5
|
|
|
|
"version": "1.0"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"templateId": "9340db83-5186-4d5b-aa98-bb0d8f99274b", "templateName": "Vue 单页应用",
|
|
|
|
"version": "2.0.0",
|
|
|
|
"description": "一个基于 Vue 的单页应用模板", "language": "JavaScript",
|
|
|
|
"buildType": "Vite",
|
|
|
|
"components": [
|
|
|
|
{
|
|
|
|
"componentId": "e543562b-b59c-4d32-b86c-183113c56159", "componentName": "Vue Router",
|
|
|
|
"description": "Vue 路由管理组件",
|
|
|
|
"type": "web",
|
|
|
|
"version": "2.0"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"componentId": "e543562b-b59c-4d32-b86c-183113c56159", "componentName": "日志处理",
|
|
|
|
6
|
|
|
|
"description": "用于处理前端日志的组件",
|
|
|
|
"type": "log",
|
|
|
|
"version": "1.0"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
],
|
|
|
|
"organization": "中国电信"
|
|
|
|
}
|
|
|
|
● 数据流向：研发云-->脚手架服务● 数据结构说明：由研发云调用脚手架服务生成模板代码，请求参数包含模板信息、组件信息等。● 数据结构定义：
|
|
|
|
7
|
|
|
|
8
|
|
|
|
Component 数据结构定义：
|
|
|
|
● 示例：
|
|
|
|
{
|
|
|
|
"templateId": "9340db83-5186-4d5b-aa98-bb0d8f99274b", "templateName": "微服务基础模板",
|
|
|
|
"version": "1.0.0", "language": "Java",
|
|
|
|
"buildType": "Maven",
|
|
|
|
"architecture": "DDD",
|
|
|
|
"projectName": "my-service",
|
|
|
|
9
|
|
|
|
"groupId": "com.example", "artifactId": "my-service",
|
|
|
|
"components": [
|
|
|
|
{
|
|
|
|
"componentId": "e543562b-b59c-4d32-b86c-183113c56159", "componentName": "数据库访问组件",
|
|
|
|
"version": "1.0.0"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"componentId": "e543562b-b59c-4d32-b86c-183113c56159", "componentName": "身份验证组件",
|
|
|
|
"version": "1.0.0"
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
#### 3.1.2 接口定义
|
|
|
|
POST 类型接口 header 信息
|
|
|
|
10
|
|
|
|
##### 3.1.2.1 模板分页查询
|
|
|
|
POST api/v1/template/page请求参数
|
|
|
|
{
|
|
|
|
"pageSize":0,
|
|
|
|
"pageIndex":0,
|
|
|
|
"templateName":"统一技术底座", "language":"Java",
|
|
|
|
11
|
|
|
|
"buildType":"Maven",
|
|
|
|
"organization":"中国电信" }
|
|
|
|
响应
|
|
|
|
{
|
|
|
|
"success": true,
|
|
|
|
"errCode": "",
|
|
|
|
12
|
|
|
|
"errMessage": "", "totalCount": 0,
|
|
|
|
"pageSize": 0,
|
|
|
|
"pageIndex": 0,
|
|
|
|
"data": [{
|
|
|
|
"templateId": "9340db83-5186-4d5b-aa98-bb0d8f99274b", "templateName": "基础 Web 应用",
|
|
|
|
"version": "1.0.0",
|
|
|
|
"description": "这是一个基础的 Web 应用脚手架", "language": "Java",
|
|
|
|
"buildType": "Maven",
|
|
|
|
"organizaion": "",
|
|
|
|
"orgDisplayName": ""
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"templateId": "8a889814-b727-4c62-bdea-c40b4cbe611a", "templateName": "Vue 单页应用",
|
|
|
|
"version": "2.0.0",
|
|
|
|
"description": "一个基于 Vue 的单页应用模板", "language": "JavaScript",
|
|
|
|
"buildType": "Vite",
|
|
|
|
13
|
|
|
|
"organizaion": "",
|
|
|
|
"orgDisplayName": ""
|
|
|
|
}],
|
|
|
|
"totalPages": 0 }
|
|
|
|
##### 3.1.2.2 组件分页查询
|
|
|
|
POST api/v1/component/page请求参数
|
|
|
|
{
|
|
|
|
"pageSize":0,
|
|
|
|
14
|
|
|
|
"pageIndex":0,
|
|
|
|
"templateId":"34242343",
|
|
|
|
"componentName":"数据库连接", "type":"database"
|
|
|
|
}
|
|
|
|
响应
|
|
|
|
{
|
|
|
|
"success": true,
|
|
|
|
15
|
|
|
|
"errCode": "",
|
|
|
|
"errMessage": "",
|
|
|
|
"totalCount": 0,
|
|
|
|
"pageSize": 0,
|
|
|
|
"pageIndex": 0,
|
|
|
|
"data": [{
|
|
|
|
"componentId": "e543562b-b59c-4d32-b86c-183113c56159", "componentName": "MySQL 数据库连接",
|
|
|
|
"description": "用于连接 MySQL 数据库的组件",
|
|
|
|
"type": "database",
|
|
|
|
"version": "1.0"
|
|
|
|
},
|
|
|
|
{
|
|
|
|
"componentId": "e543562b-b59c-4d32-b86c-183113c56159", "componentName": "JWT 认证",
|
|
|
|
"description": "基于 JWT 的认证安全组件",
|
|
|
|
"type": "security",
|
|
|
|
"version": "1.0"
|
|
|
|
}],
|
|
|
|
"totalPages": 0
|
|
|
|
}
|
|
|
|
16
|
|
|
|
##### 3.1.2.3 代码生成
|
|
|
|
POST api/v1/code/generate请求参数示例
|
|
|
|
{
|
|
|
|
"bizId": "dsdsd"
|
|
|
|
17
|
|
|
|
"templateId": "12354",
|
|
|
|
"projectName": "demo-project", "groupId": "com.demo",
|
|
|
|
"artifactId": "demo", "components": [
|
|
|
|
"db-01",
|
|
|
|
"sec-01"
|
|
|
|
]
|
|
|
|
}响应
|
|
|
|
{
|
|
|
|
"success": true,
|
|
|
|
"errCode": null,
|
|
|
|
"errMessage": null,
|
|
|
|
18
|
|
|
|
"data": {
|
|
|
|
"taskId": "3sdeeqw3" }
|
|
|
|
}
|
|
|
|
##### 3.1.2.4 代码包生成状态查询
|
|
|
|
GET api/v1/code/generate/{taskId}/states请求参数响应
|
|
|
|
19
|
|
|
|
{
|
|
|
|
"success": true,
|
|
|
|
"errCode": null,
|
|
|
|
"errMessage": null, "data": {
|
|
|
|
"taskStates":"pending" }
|
|
|
|
}
|
|
|
|
##### 3.1.2.5 代码下载
|
|
|
|
GET api/v1/code/download/{taskId}请求参数响应文件流
|
|
|
|
20
|
|
|
|
##### 3.1.2.6 代码包生成状态回调
|
|
|
|
POST api/codebackend/codeoutward/code-gen/v1/status/callback鉴权：使用统一的签名认证规范请求参数
|
|
|
|
响应
|
|
|
|
21
|
|
|
|
22
|
|
|
|
#### 3.1.3 签名认证规范
|
|
|
|
##### 3.1.3.1 签名验证流程
|
|
|
|
使用 API 参数签名算法，在跨系统接口调用时防参数篡改、防重放攻击。
|
|
|
|
a) 由脚手架服务中间层提供 secretkey；
|
|
|
|
b) 以 md5( nonce={随机字符串}×tamp={13 位时间
|
|
|
|
戳}&key={secretkey 秘钥,由脚手架服务颁发} ) 生成签名 sign。
|
|
|
|
c) 将 sign 作为参数，拼接到请求地址后面，如： http://ip:port?nonce={随机字符串}×tamp={系统当前时间戳}&sign={根据加密规则加密后的签名信 息}
|
|
|
|
23
|
|
|
|
d) 服务端接收到请求后，以同样的算法生成一次 sign。
|
|
|
|
e) 后端接收到请求后，先对比 timestamp 是否超期，再判断 nonce 是否已经使用过，然后再将参数中的 sign 跟接收到的参数重新生成的 sign 对比是否一致，如果一致则签名认证则通过，否则拒绝。
|
|
|
|
##### 3.1.3.2 签名工具类
|
|
|
|
SignUtil.java
|
|
|
|
##### 3.1.3.3 签名认证 key
|
|
|
|
由脚手架服务提供
|
|
|
|
3.1.4.脚手架服务发布地址
|
|
|
|
研发云对接脚手架生成服务 API 均发布在 zion-initializer-manage 服务中，对接地址如下：#集群内部地址
|
|
|
|
http://zion-initializer-manage:80/api/v1/*
|
|
|
|
#外部地址
|
|
|
|
http://10.200.1.168:31902/api/v1/*
|
|
|
|
### 3.2 服务部署规范
|
|
|
|
● 脚手架工具需基于研发云提供的基础设施&环境进行部署
|
|
|
|
24
|
|
|
|
■ 脚手架工具应支持 K8S 部署方式，研发云将为每个脚手架服务分配一个独立命名空间■ 脚手架工具应且仅应使用规定范围内的基础组件，包括 postgres、 redis、minio、kafka，《Redis 客户端接入手册（ACL)》■ 脚手架工具服务通过 K8S NodePort 方式暴露服务给研发云平台代码中心调用，NodePort 端口由研发云平台指定● 脚手架服务提供方需提供部署/升级所需数据库脚本■ 由脚手架服务方提供测试/生产环境数据库表初始化 ddl/迭代升级脚本■ 由研发云运维人员配合进行数据库初始化、数据订阅仓库初始化、产品升级等操作。● 服务部署应满足平台监控、日志接入管理要求● 服务部署应支持 ARM 硬件（后续信创要求）● 部署基本架构如下图所示：
|
|
|
|
25
|
|
|
|
### 3.3 订阅使用数据
|
|
|
|
研发云通过能力开放专区-数据能力，提供数据订阅明细表，接入方可订阅获取自己单位脚手架的使用数据。数据订阅参考《3 研发云互联互通规范-数据开放和接入技术规范》
|
|
|
|
## 4 脚手架维护
|
|
|
|
26
|
|
|
|
服务接入研发云后，需遵守研发云的管理规范要求，并在指定项目中协作并维护该服务。
|
|
|
|
### 4.1 申请协作项目
|
|
|
|
接入方提供项目标识、开发人员研发云账号、邮箱、SDP 账号，由研发云创建协作项目。
|
|
|
|
### 4.2 申请测试账号
|
|
|
|
接入方提供开发、测试人员姓名、手机号、邮箱，由研发云开通研发云测试环境和 SDP 账号。
|
|
|
|
### 4.3 申请生产发版
|
|
|
|
● 由接入方创建版本，并关联工作项，发版前需确认版本关联信息完整（工作项、代码、制品、安全）● 由接入方提交给研发云领导申请发版研发云生产环境，发版评审示例：
|
|
|
|
27
|
|
|
|
> 评审与传阅人员信息已移除。
|
|
|
|
> 评审与传阅人员信息已移除。
|
|
|
|
28
|