182 lines
9.7 KiB
Markdown
182 lines
9.7 KiB
Markdown
# server —— 后端
|
||
|
||
后端服务（Maven + Spring Boot）。现有代码是从原型 `fms-api` 迁入的元数据驱动引擎实现：
|
||
包名 `cn.g3soft.erp`，artifactId `erp-api`，启动类 `ErpApiApplication`。
|
||
|
||
构建 `mvnw.cmd test`；启动 `start.cmd`（`spring-boot:run`，默认 8088、context-path `/api`）。
|
||
|
||
> 迁入时**未带入**三项：流程引擎（`service/workflow`、`WorkflowController`、
|
||
> `WorkflowRuntimeController`）、数据库迁移脚本（`config/migrations`、`tools/migration`）、
|
||
> 本地文件存储数据（`data/files`）。
|
||
|
||
## 已定的技术栈
|
||
|
||
| 项 | 选型 |
|
||
|---|---|
|
||
| 框架 | Spring Boot 4.1.0 |
|
||
| 语言 | Java 21 |
|
||
| Web | spring-boot-starter-webmvc |
|
||
| 持久层 | spring-boot-starter-jdbc（**无 ORM**） |
|
||
| 连接池 | Druid 1.2.18 |
|
||
| 数据库 | **SQL Server**（mssql-jdbc） |
|
||
| 鉴权 | JJWT 0.12.6 |
|
||
| Excel | Apache Fesod 2.0.2-incubating |
|
||
| 其他 | ip2region、ua-parser |
|
||
| 构建 | Maven |
|
||
|
||
## IP 归属地
|
||
|
||
登录日志里的 IP 归属地走**本地 `ip2region` 库**，不联网。实测：加载 5~7ms，单次查询 1~4 微秒，
|
||
所以它不构成启动瓶颈（应用自身启动约 1.2~1.7s）。
|
||
|
||
> **部署须知**：`ip2region.xdb`（约 11MB）被 `.gitignore` 排除，不在仓库里，部署时必须手工放到
|
||
> `src/main/resources/`。漏放**不会导致启动失败**，只会让所有归属地静默变成「未知」。
|
||
|
||
内网 / 保留地址（RFC1918、回环、链路本地、IPv6 ULA）直接记「内网」，不外呼。
|
||
|
||
## 日志
|
||
|
||
### 输出与落盘
|
||
|
||
控制台输出彩色文本；文件输出**结构化 JSON**（每行一个对象，logstash 格式），默认落在 `server/logs/`
|
||
（相对进程工作目录的 `./logs`，根 `.gitignore` 已忽略）。
|
||
|
||
| 文件 | 内容 |
|
||
|---|---|
|
||
| `logs/erp-api.jsonl` | 全量日志 |
|
||
| `logs/erp-api-error.jsonl` | 仅 `ERROR` |
|
||
| `logs/erp-api.<日期>.<序号>.jsonl.gz` | 滚动归档（gzip） |
|
||
|
||
滚动策略：单文件 10MB、保留 30 天；主文件总量上限 1GB、错误文件 256MB。文件写入经 `AsyncAppender`，
|
||
队列满时**背压而非丢日志**，不阻塞请求线程。
|
||
|
||
配置在 `src/main/resources/logback-spring.xml`（appender / 滚动 / 编码器）+ `application.yaml` 的 `logging` 块（路径 / 格式 / 级别）。
|
||
|
||
> **必须命名为 `logback-spring.xml`**：结构化编码器依赖 Spring 注入的 `Environment`，改成 `logback.xml` 会启动失败。
|
||
|
||
### 请求追踪
|
||
|
||
每个请求分配一个 `traceId`（优先复用上游 `X-Request-Id` / W3C `traceparent`），并回写到响应头 `X-Request-Id`。
|
||
通过 `MDC` 注入，因此**该请求的所有日志行**都带同一 `traceId`，按它即可串起完整链路。
|
||
|
||
> 入参 `X-Request-Id` 需匹配 `^[A-Za-z0-9._-]{8,64}$` 才会被复用，否则**静默忽略并自行生成**（防日志注入 / 换行伪造）。
|
||
> 若发现上游的 traceId 没串起来，先检查这个格式约束。W3C `traceparent` 则要求标准 `00-<32hex>-<16hex>-<2hex>` 格式。
|
||
|
||
访问日志每请求一行（`logger_name=ACCESS`、`message=http_access`）。主要字段（均为 JSON 顶层字段）：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `@timestamp` / `level` / `logger_name` / `thread_name` | 标准字段 |
|
||
| `traceId` | 请求链路 ID |
|
||
| `method` / `uri` | `uri` 仅为 path，**不含 query** |
|
||
| `status` / `durationMs` / `slow` | HTTP 状态 / 耗时 / 是否超过慢请求阈值 |
|
||
| `orgId` / `userId` | 鉴权通过后由 `JwtAuthFilter` 回写 MDC |
|
||
| `clientIp` / `userAgent` | 客户端信息（`userAgent` 截断 256 字符） |
|
||
| `params` | 请求参数，**仅错误或慢请求时出现** |
|
||
| `stack_trace` | 异常堆栈，仅错误行 |
|
||
|
||
> 注意：本项目异常统一返回 **HTTP 200**，错误码在响应 body 里。所以判断出错要看 `level` / `erp-api-error.jsonl`，**不能看 `status`**。
|
||
> 另外，被 `JwtAuthFilter` 直接拒绝的请求（未登录 / 会话被顶）不会读取 body，因此没有 `params`。
|
||
|
||
### 请求参数记录
|
||
|
||
请求参数（query + body）**只在出错或慢请求时**记录到 `params`，正常请求不记，避免刷屏与大 body 常态落盘；
|
||
文件上传（multipart / 二进制流）跳过，超出上限按 UTF-8 字节边界截断（不会切断中文）。
|
||
|
||
```yaml
|
||
erp:
|
||
log:
|
||
slow-request-ms: 1000 # 超过则视为慢请求，记录 params
|
||
max-param-bytes: 2048 # 参数记录上限(字节)，同时是请求体缓存上限
|
||
exclude-param-paths: # 这些路径完全不记参数（与 getServletPath() 精确匹配）
|
||
- /auth/login # 登录接口含明文密码，默认排除
|
||
```
|
||
|
||
> **不做脱敏**：除 `exclude-param-paths` 外，参数原样写入日志（含业务数据、明文密码）。
|
||
> 上线前请确认日志文件的访问权限与流转范围；如需收口，把对应接口加进排除名单即可。
|
||
|
||
### 分级与噪音
|
||
|
||
`ERROR`=系统故障、`WARN`=降级 / 预期内业务竞争、`INFO`=生命周期与访问、`DEBUG`=排障。
|
||
第三方噪音（Druid、SQL Server JDBC、Spring）默认降到 `WARN`，可在 `application.yaml` 的 `logging.level.*` 调整；
|
||
临时排障时可把 `cn.g3soft.erp` 调到 `DEBUG`。
|
||
|
||
> **级别以 `application.yaml` 为准**：`logback-spring.xml` 里也给 `cn.g3soft.erp` / `ACCESS` 各写了一份 `INFO`，
|
||
> 但 Boot 是在加载 logback 配置**之后**才应用 `logging.level.*`，所以 YAML 会覆盖 XML。**改级别请改 YAML**，
|
||
> XML 里那两行只是兜底默认值。
|
||
|
||
### 查看与分析
|
||
|
||
- **图形界面**：双击 `server/log-viewer.html`（Edge / Chrome），选择 `logs`（或 `logs-demo`）文件夹即可。
|
||
支持 `.jsonl` 与轮转 `.gz`，**本地解析、不上传**。提供概览 / 错误 / 慢请求 / 按机构 / 按接口 / 状态码 / 按小时 / traceId 追踪。
|
||
- **命令行**：活动文件直接 `jq`，归档用 `gzip -dc`；Windows 亦可用自带 PowerShell（`ConvertFrom-Json`），无需安装 jq。
|
||
- `server/logs-demo/` 是**模拟日志**（已 gitignore），仅用于演示查看器，可随时删除。
|
||
|
||
## 数据访问层（`cn.g3soft.erp.database`）
|
||
|
||
`database` 下分两块，**两者零互相引用**（一边管"连接怎么来"，一边管"拿到连接后怎么读写"）：
|
||
|
||
| 包 / 类 | 职责 |
|
||
|---|---|
|
||
| `database/`（根） | 通用数据访问，方法都走 JDBC、无 ORM |
|
||
| `database.MetadataReader` | 表结构内省：`loadTableMetadata` / `getColumn` / `describeColumns`；列名归一化也在这里 |
|
||
| `database.RowReader` | 只读查询与分页：`loadData` / `loadDataBySql` / `page`；唯一持有默认数据源 |
|
||
| `database.RowWriter` | 通用写入与条件更新语义：`insert` / `update` / `delete`、`$original` / `$expr` / guard、零行原因定位 |
|
||
| `database.model` | 纯数据载体，无任何逻辑：`TableMetadata` / `ColumnMetadata` / `PageResult` / `GuardCondition` / `ZeroRowCause` |
|
||
| `database.org` | 多机构数据库连接：`OrgContext`（请求级机构/用户上下文）、`OrgDatabaseProperties` / `OrgDatabaseConfig*`（配置与热加载）、`OrgDataSourceFactory` / `OrgDataSourceManager` / `OrgRoutingDataSource`（装配与路由） |
|
||
| `common.util.SqlText` | SQL 文本与安全校验：标识符校验与加引号、只读 SQL 校验、排序子句构建；纯静态 |
|
||
|
||
三条约定：
|
||
|
||
1. `SqlText` 不依赖任何人，所以依赖方向固定为 `service → database → common`，不成环。
|
||
2. `RowReader` 之外的方法都接收调用方传入的 `Connection`（不自己开事务），事务边界留在服务层。
|
||
3. 认证要按 `orgId` 取该机构连接（登录时机构上下文尚未建立），所以那条查询在
|
||
`service.auth.UserAccountReader` 里，**不在**访问层。
|
||
|
||
## 分割现状与规划
|
||
|
||
**现状**（迁入的原型代码，已按职责归过一轮）：
|
||
|
||
```
|
||
cn.g3soft.erp
|
||
├── common/ # 通用返回、异常、纯静态工具
|
||
│ ├── ApiResponse.java # HTTP 响应外壳 + 全部错误码常量
|
||
│ ├── exception/ # 6 个异常与 GlobalExceptionHandler
|
||
│ └── util/ # ParamUtils / SqlText / StringUtils / TimeUtils / RequestParams /
|
||
│ # UuidV7Generator + snowflake/（内嵌的雪花 ID 生成器）
|
||
├── config/ # AuthProperties / LogProperties / FileStorageProperties /
|
||
│ # JacksonConfig / JwtAuthFilter / RequestLoggingFilter
|
||
├── controller/ # 6 个 Controller
|
||
├── database/ # 数据访问层（见上）：RowReader / RowWriter / MetadataReader + model/ + org/
|
||
└── service/
|
||
├── auth/ # 登录、会话、登录日志、JwtUtils，以及 client/（客户端信息采集）
|
||
├── data/ # 通用保存 / 删除 / 查询编排
|
||
├── export/ file/ formula/ permission/
|
||
```
|
||
|
||
**规划**（新代码按此落位，老代码后续按域重构）：
|
||
|
||
```
|
||
cn.g3soft.erp
|
||
├── common/ # 通用返回、异常、工具 —— 已建
|
||
├── engine/ # 元数据驱动引擎（查询 / 保存 / 权限）—— 未设计；
|
||
│ # 现在的 database + service/{data,formula,permission} 是它的雏形
|
||
└── module/
|
||
├── ocean/ # 海运
|
||
├── air/ # 空运
|
||
├── container/ # 箱管
|
||
├── finance/ # 财务
|
||
├── crm/ # CRM
|
||
└── system/ # 系统管理
|
||
```
|
||
|
||
## 与前端的关系
|
||
|
||
**唯一契约是 HTTP 接口。** 前端不读后端源码，后端不管前端怎么调。
|
||
|
||
同仓的三条纪律（见根 `README.md`）：
|
||
|
||
1. **独立构建** —— `mvn package` 不触发前端构建，反之亦然
|
||
2. **独立版本** —— tag 分开打（`api-v1.2.0` / `web-v1.2.0`）
|
||
3. **接口契约写进 `docs/`** 并版本化
|