session-service 技术文档

一、镜像概述和主要用途

session-service 是一个用于 cBioPortal 会话管理的 RESTful API 服务，基于 MongoDB 存储会话数据。该服务将会话信息以 JSON 格式持久化，具备通用性，可扩展至任何 JSON 对象的存储与管理。其核心功能是为 cBioPortal 相关应用提供会话数据的创建、查询、更新和删除（CRUD）操作接口。

二、核心功能和特性

1. RESTful API 接口：提供标准的 HTTP 方法（POST/GET/PUT/DELETE）实现会话数据的完整生命周期管理。
2. 多会话类型支持：预定义多种会话类型（如 main_session、virtual_study 等），适配不同业务场景（结果页查询、虚拟研究、比较页查询等）。
3. MongoDB 数据存储：使用 MongoDB 作为后端数据库（默认数据库名 session_service），支持高可用和可扩展的数据存储。
4. 灵活的认证机制：可选启用基本认证（Basic Authentication），通过配置控制访问权限。
5. Swagger 文档集成：内置 Swagger UI，自动生成 API 文档（访问路径：http://[服务地址]:[端口]/swagger-ui.html）。
6. 跨部署模式支持：支持 Docker 容器化部署和传统 JAR/WAR 包部署，适配不同运维环境。

三、使用场景和适用范围

适用场景

• cBioPortal 会话管理：存储用户在 cBioPortal 中的查询结果、页面配置、自定义数据等会话信息。
• 多类型数据持久化：支持虚拟研究（virtual_study）、比较页查询（comparison_session）、自定义基因列表（custom_gene_list）等场景的数据存储。
• Web 应用状态管理：为需要持久化用户操作状态的 Web 应用提供通用 JSON 数据存储接口。

适用范围

适用于基于 cBioPortal 开发的生物信息学平台、需要管理用户会话数据的 Web 应用，或任何需通过 API 接口存储 JSON 结构数据的场景。

四、使用方法和配置说明

4.1 Docker 部署

4.1.1 环境要求

• Docker Engine 19.03+
• Docker Compose 1.27+

4.1.2 部署步骤

启动服务

通过 docker-compose 启动服务（默认使用项目根目录下的 docker-compose.yml 配置）：

# 前台运行（日志实时输出）
docker-compose up

# 后台运行（detached 模式）
docker-compose up -d

停止服务

后台运行模式下停止服务：

docker-compose down

重建镜像

开发环境中修改代码后，需重建镜像并重启：

docker-compose up --build

验证服务状态

服务启动后，访问以下地址验证是否运行正常（返回版本号即表示成功）：

curl http://localhost:8080/info

4.1.3 测试会话创建

通过 curl 命令测试会话创建接口（默认未启用认证，若启用需添加 --user user:pass 参数）：

curl -H "Content-Type: application/json" -X POST http://localhost:8080/api/sessions/test_portal/main_session \
  --data '{"title": "我的主门户会话", "description": "这是一个示例会话"}'

成功响应：返回状态码 200 和会话 ID（如 {"id": "57167a52ef86d81afb415aba"}）。

4.1.4 连接 MongoDB 数据库

默认配置下 MongoDB 端口不对外暴露，需通过容器内部连接：

# 进入 MongoDB 容器（容器名默认：session-service_db_1）
docker exec -it session-service_db_1 mongo mongodb://localhost:27017

4.2 非 Docker 部署

4.2.1 环境要求

• JDK 1.7+
• Maven 3.0+
• MongoDB 3.0+（需提前启动并监听默认端口 27017）

4.2.2 部署步骤

1. 准备 MongoDB 数据库

通过 MongoDB Shell 创建默认数据库 session_service：

mongo  # 进入 MongoDB Shell
> use session_service  # 创建并切换到数据库 session_service

2. 编译与启动服务

克隆代码仓库并通过 Maven 编译运行：

# 克隆仓库
git clone [***]
cd session-service

# 编译打包（生成 JAR 包）并启动服务
mvn package -Dpackaging.type=jar && \
java -Dspring.data.mongodb.uri=mongodb://localhost:27017/session-service \
  -jar target/session_service-0.1.0.jar

3. 生成 WAR 包（可选）

如需部署到 Java Web 容器（如 Tomcat），可生成 WAR 包并自定义配置：

# 创建配置文件目录
mkdir src/main/resources/
# 复制自定义配置文件（示例配置见 4.3 节）
cp /path/to/custom.config src/main/resources/
# 编译生成 WAR 包
mvn package

五、配置说明

5.1 配置文件参数

通过配置文件（默认路径 src/main/resources/application.properties 或 application.yml）自定义服务行为，支持以下核心参数：

5.2 环境变量

通过环境变量覆盖默认配置，优先级高于配置文件：

5.3 配置示例

基础配置（application.properties）

# MongoDB 配置
spring.data.mongodb.database=session_service
spring.data.mongodb.host=mongodb-host
spring.data.mongodb.port=27017

# 服务端口与上下文路径
server.port=8081
server.contextPath=/session-service

# 启用基本认证
security.basic.enabled=true
spring.security.user.name=admin
spring.security.user.password=secret123

六、API 文档

6.1 文档访问

服务启动后，通过 Swagger UI 查看完整 API 文档：

http://[服务地址]:[端口]/swagger-ui.html  

（若启用基本认证，需通过 [***][服务地址]:[端口]/swagger-ui.html 访问）

6.2 会话类型

服务支持以下预定义会话类型，用于区分不同业务场景：

6.3 核心接口

6.3.1 创建会话

请求：POST http://[服务地址]:[端口]/api/sessions/{source}/{type}/

• source：会话来源（如 msk_portal，区分不同应用）
• type：会话类型（需为 6.2 节中定义的有效类型）
• 请求体：JSON 格式的会话数据

示例：

curl -H "Content-Type: application/json" --user user:pass -X POST \
  http://localhost:8080/api/sessions/msk_portal/main_session \
  --data '{"title": "我的主门户会话", "description": "这是一个示例"}'

响应：

• 成功：状态码 200，返回会话 ID

  {"id": "57167a52ef86d81afb415aba"}
  

• 失败：状态码 400（无效类型或空请求体）

6.3.2 查询会话列表

请求：GET http://[服务地址]:[端口]/api/sessions/{source}/{type}/

• source：会话来源
• type：会话类型

响应：

• 成功：状态码 200，返回会话列表（包含 id、data、source、type）

  [
    {
      "id": "57167a52ef86d81afb415aba",
      "data": {"title": "我的主门户会话", "description": "这是一个示例"},
      "source": "msk_portal",
      "type": "main_session"
    }
  ]
  

6.3.3 查询单个会话

请求：GET http://[服务地址]:[端口]/api/sessions/{source}/{type}/{id}

• id：会话 ID（创建会话时返回）

响应：

• 成功：状态码 200，返回单个会话详情
• 失败：状态码 404（会话不存在）

6.3.4 更新会话

请求：PUT http://[服务地址]:[端口]/api/sessions/{source}/{type}/{id}

• 请求体：更新后的 JSON 会话数据

示例：

curl -H "Content-Type: application/json" --user user:pass -X PUT \
  http://localhost:8080/api/sessions/msk_portal/main_session/57167a52ef86d81afb415aba \
  --data '{"title": "更新后的主门户会话", "description": "这是更新示例"}'

响应：

• 成功：状态码 200（无响应体）
• 失败：状态码 400（空请求体）或 404（会话不存在）

6.3.5 删除会话

请求：DELETE http://[服务地址]:[端口]/api/sessions/{source}/{type}/{id}

响应：

• 成功：状态码 200（无响应体）
• 失败：状态码 404（会话不存在）

6.3.6 条件查询会话

请求：GET http://[服务地址]:[端口]/api/sessions/{source}/{type}/query?field={field}&value={value}

• field：查询字段（如 data.title）
• value：字段值（URL 编码）

示例：

curl --user user:pass "http://localhost:8080/api/sessions/msk_portal/main_session/query?field=data.title&value=我的主门户会话"

响应：状态码 200，返回匹配的会话列表。

6.4 注意事项

• 大小写敏感：source、type 和 id 参数区分大小写（如 MSK_portal 与 msk_portal 视为不同来源）。
• 认证要求：启用基本认证后，所有接口需通过 --user {username}:{password} 传递认证信息。