# microservices

**Repository Path**: cms05/microservices

## Basic Information

- **Project Name**: microservices
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-11
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 实验室资源管理系统（跨语言微服务）

本项目构建跨语言微服务体系：Java 统一网关整合 Node.js 物资管理与 Python 借用记录服务，对外提供一致的 REST 接口。

## 完成情况概览

- 统一网关与 REST 接口
  - Java 网关（`gateway/`）运行端口 `8080`，已提供统一入口：
    - 人员管理：`GET/POST/PUT/DELETE /api/persons`（本地持久化，JPA）
    - 物资管理代理：`/api/materials*` 透传至 `http://materials:8082/materials*`
    - 借用记录代理：`/api/borrows*` 透传至 `http://app:8081/borrows*`
  - `application.yml` 明确端口与下游地址，支持通过环境变量覆盖。

- 跨语言微服务与端口
  - Python/Flask 借用记录（`app/src/main.py`）：端口 `8081`
    - 已实现 `/borrows` 的增删改查（内存存储），并提供健康根路径 `/`
  - Node.js/Express 物资管理（`materials/src/index.js`）：端口 `8082`
    - 已实现 `/materials` 的增删改查（内存存储），并提供健康根路径 `/`
  - Java/Spring Boot 人员管理（在网关内实现）：端口 `8080`
    - 实体 `Person`、`PersonRepository`、`PersonController` 完整 CRUD，默认 H2，可切 MySQL。

- 部署与编排
  - `docker-compose.yml` 已配置 `mysql`、`gateway`、`materials`、`app` 四个服务：
    - 网关通过环境变量连接 MySQL：`SPRING_DATASOURCE_URL/USERNAME/PASSWORD/DRIVER`
    - 下游地址指向容器名：`MATERIALS_URL=http://materials:8082`，`BORROWS_URL=http://app:8081`
    - 端口映射齐全：`8080/8081/8082/3306`
  - 各服务 `Dockerfile` 存在，可构建镜像。

- API 文档
  - `docs/api.md` 已提供统一网关 REST 文档，覆盖 `persons/materials/borrows` 的接口、示例与错误码。

- 前端与展示
  - `web/src/index.js` 已集成：从 `GATEWAY_URL`（默认 `http://localhost:8080`）读取 `/api/persons`、`/api/materials`、`/api/borrows` 并渲染页面。
  - 放宽 CSP 以便本地调用；提供简单错误提示与卡片状态。

- 远程调用与跨语言协作
  - 统一由 Java 网关对外暴露 REST，透传至 Node/Python 下游，满足“多个语言实现 + 可互相调用 + 统一 REST 网关”的核心要求。
  - Python `app/src/main.py` 提供借用记录 `/borrows` API；当前不包含对 `bill` 的 `/query` 演示（已移除示例依赖）。

## 快速启动

**本地手动启动（不使用 Docker）**
- 启动 Python Borrows（8081）：
```
cd app/src
python main.py
```
- 启动 Node Materials（8082）：
```
cd materials
npm install
npm run start
```
- 启动 Java Gateway（8080）：
```
cd gateway
mvn spring-boot:run
```
- 启动 Web 前端（3000）：
```
cd web/src
npm install
node index.js
```

**环境变量与配置**
- 网关数据库（默认 H2 内存库）：
  - `SPRING_DATASOURCE_URL`（示例：`jdbc:mysql://localhost:3306/gatewaydb?useSSL=false&serverTimezone=UTC`）
  - `SPRING_DATASOURCE_USERNAME`
  - `SPRING_DATASOURCE_PASSWORD`
  - `SPRING_DATASOURCE_DRIVER`（MySQL 为 `com.mysql.cj.jdbc.Driver`）
- 网关下游服务地址（若端口或部署位置不同可覆盖）：
  - `MATERIALS_URL`（默认 `http://localhost:8082`）
  - `BORROWS_URL`（默认 `http://localhost:8081`）
- Web 前端网关地址：
  - `GATEWAY_URL`（默认 `http://localhost:8080`）

**快速创建示例数据**
- 通过网关统一入口：
```
curl -X POST http://localhost:8080/api/persons \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","email":"alice@example.com"}'

curl -X POST http://localhost:8080/api/materials \
  -H 'Content-Type: application/json' \
  -d '{"name":"Book A","quantity":3,"description":"Intro"}'

curl -X POST http://localhost:8080/api/borrows \
  -H 'Content-Type: application/json' \
  -d '{"borrower":"Alice","item":"Book A","date":"2025-11-10"}'
```
- 查看列表：
```
curl http://localhost:8080/api/persons
curl http://localhost:8080/api/materials
curl http://localhost:8080/api/borrows
```

**常见问题排查**
- 端口占用：确保 `8080/8081/8082/3000/3306` 未被其他程序占用；修改对应端口或关闭占用程序。
- 网关启动报错（数据库）：
  - 未配置 MySQL 时默认使用 H2；如需 MySQL，确认库已创建、凭据正确、驱动设置为 `com.mysql.cj.jdbc.Driver`。
- 下游服务未启动：
  - Web 卡片显示空数组或错误信息通常是后端服务未启动；按“本地手动启动”启动 `materials/app/gateway` 后刷新页面。
- 跨域/内容安全策略（CSP）：
  - Web 已设置宽松 CSP 允许本机端口调用；若部署到其他主机需同步调整。
  
## 快速创建示例数据

```bash
# 创建人员
curl -X POST http://localhost:8080/api/persons \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","email":"alice@example.com"}'

# 创建物资
curl -X POST http://localhost:8080/api/materials \
  -H 'Content-Type: application/json' \
  -d '{"name":"Book A","quantity":3,"description":"Intro"}'

# 创建借用记录
curl -X POST http://localhost:8080/api/borrows \
  -H 'Content-Type: application/json' \
  -d '{"borrower":"Alice","item":"Book A","date":"2025-11-10"}'
```

## 参考

- 统一 API 文档：`docs/api.md`
- 架构图：`diagram.png`