Skip to main content

如何开发一个平台后端服务

本文将介绍如何开发一个自己的后端服务, 并打包和部署到平台中.

介绍​

当需要扩展平台功能，或者需要实现系统集成时，可以开发一个独立的服务程序，然后将该服务打包并部署到平台中.

后端服务大概分为两类:

  • 一类是运行一些后台任务, 例如: 定时任务, 事件处理等. 该类服务通常不对外提供接口
  • 另一类是提供一些接口供前端调用

这两类服务在开发上是相同的, 在打包方面稍有不同. 本文将以 Java 语言为例介绍如何开发第二类服务.

开发步骤​

接下来将会详细介绍如何开发一个 Java 后端服务, 以及如何将该服务打包并部署到平台中.

1. 创建项目​

与 Java SDK 中的数据接入驱动开发类似, 创建一个标准的 springboot 项目即可. 项目创建完成后, 根据自己业务的需求向项目中添加相应的依赖包. 可以参考 数据接入驱动开发-创建项目.

info

如果业务中需要访问平台接口, 需要引入 Java SDK, 详情见 平台接口客户端

2. 根据自身业务需求实现代码​

这一步骤与普通的 springboot 项目开发没有区别, 根据自己的业务需求实现相应的代码即可. 如果涉及平台接口的调用, 请查看 平台接口客户端 内容.

info

对于开发第二类服务来说, 需要服务内的所有接口提供统一的请求前缀, 例如: /my-service, 这样平台才能正确的代理该服务. 该前缀可以在 application.yml 文件中配置, 例如:

server:
  servlet:
    context-path: /my-service

3. 打包​

这一步骤介绍如何将一个开发好的 Java 程序打包为可在平台部署的安装包.

平台中使用 traefik 组件作为平台网关, 可以为平台中的后端服务提供统一的访问入口、负载均衡、统一认证等功能. 所以, 当开发第二类后端服务时, 需要在程序之外额外提供一些配置信息, 以便 traefik 能够正确识别和代理后端服务, 这些配置信息保存在 service.yml 文件中, 需要和程序一起打包.

1. 打包程序​

使用 springboot 自带的打包插件将程序代码打包为 jar 文件. 该过程与普通的 springboot 项目打包没有区别.

# 使用 maven 打包
mvn clean package

2. 程序配置说明​

springboot 程序的配置文件通常保存在 application.yml 文件中. 如果部署在 windows 平台时, 要求配置文件 application.yml 必须放在 jar 包外面, 因为平台在安装服务时, 需要读取该配置文件的内容.

info

springboot 默认从多个路径读取配置文件, 可以将 application.yml 和 jar 文件放在同一个目录下, 或者放在 jar 文件同级目录 config 中.

3. 编写 service.yml​

该文件内容描述了服务的一些信息, 平台通过该配置文件的内容来识别服务以及配置反向代理等功能. windows 平台和 linux 平台配置文件内容有所不同, 请根据自己的平台选择相应的配置文件.

linux 平台文件内容介绍如下​
# 必填项. 服务名称
Name: my-service
# 必填项. 如果驱动对外提供 rest 服务, 则需要填写 rest 接口的统一路径前缀.
# 当开发第二类服务时, 该配置项内容需要与 server.servlet.context-path 的值保持一致.
Path: /my-service
# 必填项. 服务的版本号. 例如: 1.0.0
Version: 1.0.0
# 非必填项.
Description: 服务的描述信息
# 必填项. 固定为 server
GroupName: server
# 服务端口映射类型, 必填项. 
# 可选项有 None Internal External
# 
# None: 不暴露端口
# Internal: 只在平台内部暴露端口. 一般为驱动对外提供 rest 服务时, 将端口映射到网关上, 填写为 Internal 即可.
# External: 同时将端口映射到网关和宿主机上.
Service: Internal
# 非必填项. 暴露的端口列表. 对于第二类服务该配置项必填.
Ports:
  - Host: "8558"            # 映射到宿主机的端口号, 如果不填写, 则会随机分配一个端口号
    Container: "8558"       # 服务监听的端口号, 即配置文件中 server.port 的值
    Protocol: ""            # 协议类型, 可选项有 TCP UDP, 如果不填写, 则默认为 TCP
windows 平台文件内容介绍如下​
# 必填项. 服务名称
Name: my-service
# 必填项. 如果驱动对外提供 rest 服务, 则需要填写 rest 接口的统一路径前缀.
# 当开发第二类服务时, 该配置项内容需要与 server.servlet.context-path 的值保持一致.
Path: /my-service
# 必填项. 例如: 1.0.0
Version: 1.0.0
# 非必填项.
Description: 服务的描述信息
# 服务配置文件名称. 平台安装服务时会查找并读取该文件. 一般填写 application.yml
ConfigType: application.yml
# 必填项. 固定为 server
GroupName: server
# 必填项. 启动命令. 还可以添加一些启动参数, 例如: -Xms512m -Xmx1024m
Command: java -jar my-service.jar

4. 打包​

该步骤是将前面已经打包好的 jar 文件和 service.yml 文件打包为一个安装包, 以便平台安装服务时能够正确识别服务.

linux 平台打包​

在 linux 平台上, 平台服务是以 docker 容器的形式运行的, 需要将服务程序打包为一个 docker 镜像. 然后再将镜像和service.yml 文件打包为压缩文件. 以下是简单的 Dockerfile 示例:

FROM openjdk:11.0.13-jre-slim-bullseye

WORKDIR /app

# 将之前打包好的 jar 文件复制到镜像中
COPY target/my-service-*.jar /app/my-service.jar

# 容器的启动命令
CMD ["java", "-jar", "my-service.jar"]
# 打包镜像
docker build -t my-service:v1.0.0 .

将构建好的镜像和 service.yml 文件打包为一个压缩文件即可. 例如:

# 导出镜像并压缩
docker save my-service:v1.0.0 | gzip > my-service.tar.gz

# 将 service.yml 文件和镜像打包为一个压缩文件
tar czvf my-service-linux-x86-64.tar.gz service.yml my-service.tar.gz

最后得到的 my-service-linux-x86-64.tar.gz 文件即为平台可识别的安装包. 压缩包内部结构如下图所示:

linux 平台安装包结构

windows 平台打包​

在 windows 平台上, 平台服务是直接运行的, 需要将 jar 文件、application.yml 和 service.yml 文件打包为 zip 格式压缩文件. 压缩包内部结构如下图所示:

windows 平台安装包结构

info

平台中默认安装了 jdk17 的环境, 如果使用的版本高于该版本, 需要自己提供额外的 jdk 环境, 并且修改 service.yml 中的 Command 配置项.

5. 部署​

该步骤介绍如何将上一步骤中打包好的安装包部署到平台中.

  1. 打开平台运维管理系统并登录. 默认地址为: http://ip:13030.
  2. 登录成功后, 点击左侧导航栏中的 服务管理 菜单, 进入服务管理页面.
  3. 点击右上角的 添加服务 按扭, 然后选择 离线添加 标签页.
  4. 点击 上传 按扭, 选择上一步骤中打包好的安装包, 然后点击 提交 按钮, 等待平台的安装过程完成即可.
  5. 如果安装成功, 则可以在服务管理页面中看到刚刚安装的服务. 如果安装失败, 可以回到首页查看安装日志, 并根据日志信息进行排查.

安装过程序如下图所示:

部署服务

4. 访问​

当服务安装成功后, 如果是第二类服务, 那么该服务内的接口就可以通过平台网关进行访问了. 例如: 如果服务内有一个接口地址为: GET /student/{id}, 那么可以通过 http://ip:31000/my-service/student/1 来访问该接口.

# 使用 curl 访问
curl -X GET -H "Authorization:Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTYyMjU5ADQsImlhdCI6MTY5NTAxNjM4NCwibmJmIjoxNjk1MDE2Mzg0LCJzdWIiOiJhZG1pbiIsInByb2plY3RJZCI6IjY0MDU5OTVlYmUyZDg0MmI2MWRmZWQyYSJ9.Flv4Md5KzOIG0oNPsm_TG9ucNRYZMOW9PSAseaLpLfsQgDgiI-Jo1KOOskbUhiBi4fS4riyEcSWZQMGuXGu8og" http://ip:31000/my-service/student/1
info

注意事项:

  1. 访问安装到的平台的服务时, 需要在请求头中携带有效的平台 token, 请求头为 Authorization. 如果想禁用到平台的认证功能, 需要在运维管理系统中, 修改该服务的配置并重启. 修改方法见 如何禁用服务认证功能.
  2. 通过网关访问接口时, 必须添加统一的路径前缀, 即 service.yml 中的 Path 配置项.

其它​

如何禁用服务认证功能​

平台网关代理后端服务时, 默认会开启统一的身份认证功能. 如果请求头中没有携带有效的 token, 则会返回 401 错误. 可按以下步骤进行操作, 然后重启服务即可.

  1. 打开平台运维管理系统并登录. 默认地址为: http://ip:13030.
  2. 登录成功后, 点击左侧导航栏中的 服务管理 菜单, 进入服务管理页面.
  3. 点击右上角的 工具 -> 编辑部署文件 按扭.
  4. 找到自己的服务.
  5. 删除 traefik.http.routers.my-service.middlewares=auth.
  6. 保存, 然后重启该服务即可.

禁用认证功能-图1 禁用认证功能-图2