lixi
209021e7d2
- 新增 development/iterations/iteration-1/：15 份角色报告 + 进展看板（已完成/未闭环/下一步），作为双人协作的进度事实来源 - 新增 ADR-006：测试与交付容器化策略（Testcontainers / 交付 Docker 包 / 本机库仅个人联调） - Git 工作流规范补充：敏感信息只进忽略文件或 sample、测试数据不入库、测试代码限标准测试目录 - 门禁：mkdocs build --strict 通过（零警告）
102 lines
7.6 KiB
Markdown
102 lines
7.6 KiB
Markdown
# 07 后端工程基线改造报告（第一迭代）
|
||
|
||
- 执行人：Senior Developer
|
||
- 日期：2026-09-03
|
||
- 仓库：`patbond-api`（改动全部留在工作区，未提交）
|
||
- 范围：ADR-001（升 Boot 3）、ADR-002（移除 Nacos）落地 + 审计问题 B1（零测试）、M2（common 依赖污染）、M3（无 Maven Wrapper）、M4（启动文档/配置）整改。不含数据库、JWT、refresh token、OpenAPI（后续工单）。
|
||
|
||
---
|
||
|
||
## 1. 所升版本
|
||
|
||
| 项 | 原值 | 新值 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| Spring Boot | 2.7.18 | **3.5.16** | 3.5 线最新补丁版（写作时 Maven Central 实查） |
|
||
| Spring Cloud | 2021.0.9 | **2025.0.3** | 与 Boot 3.5 配套版本线；仅使用 OpenFeign |
|
||
| Spring Cloud Alibaba | 2021.0.6.0 | **移除** | ADR-002；BOM、两个 nacos starter、`spring.config.import` 全部删除 |
|
||
| Java 基线 | 17（source/target） | 17（`<release>17</release>` + `<parameters>true</parameters>`） | `release` 严格锁定 API 基线；`-parameters` 是 Boot 3.2+ 参数名推断的硬要求 |
|
||
| 命名空间 | `javax.validation` | `jakarta.validation` | 6 个源文件迁移，源码中已无任何 `javax.*` |
|
||
| 构建工具 | 依赖本机 mvn | **Maven Wrapper（mvnw，Maven 3.9.16）** | `mvn wrapper:wrapper` 生成 |
|
||
|
||
本机默认 JDK 为 26，构建/运行统一以 `JAVA_HOME=/usr/lib/jvm/java-17-openjdk` 执行（README 已写明）。
|
||
|
||
## 2. 改动文件清单
|
||
|
||
**pom（4 个，修改）**
|
||
- `pom.xml`：Boot/Cloud 版本升级、删 Alibaba BOM、compiler 改 `release`+`parameters`、pin surefire 3.5.2。
|
||
- `patbond-common/pom.xml`：**瘦身为纯契约模块**——只保留 `jakarta.validation-api`（compile）+ `spring-boot-starter-test`（test）；删除 web/amqp/openfeign/loadbalancer/nacos-discovery/nacos-config/hutool/lombok（M2 关闭，对齐开发计划 4.1）。
|
||
- `patbond-user/pom.xml`：自持 `starter-web`、`starter-validation`（原经 common 传递），保留 `spring-security-crypto`，新增 `starter-test`。
|
||
- `patbond-auth/pom.xml`：自持 `starter-web`、`starter-validation`、`spring-cloud-starter-openfeign`（不显式引 loadbalancer），新增 `starter-test`。
|
||
|
||
**Java 源码（6 个，修改）**
|
||
- `patbond-auth/.../client/UserClient.java`：`@FeignClient(name = "patbond-user", url = "${patbond.user-service.url}")`（ADR-002 静态地址）。
|
||
- `AuthController.java`、`LoginRequest.java`、`RegisterRequest.java`、`UserController.java`、`CreateUserRequest.java`、`VerifyPasswordRequest.java`：javax→jakarta。
|
||
|
||
**配置（按用户中途指示采用 sample 模式：`application.yml` 保持 git 忽略，sample 入库）**
|
||
- 更新 `patbond-user/src/main/resources/application.yml.sample`（去 Nacos；`PATBOND_USER_PORT:8082`）。
|
||
- 更新 `patbond-auth/src/main/resources/application.yml.sample`（去 Nacos；`PATBOND_AUTH_PORT:8081`、`patbond.user-service.url: ${PATBOND_USER_SERVICE_URL:http://127.0.0.1:8082}`）。
|
||
- `.gitignore`：保留 `application.yml` 忽略 + `.sample` 白名单规则（去掉的是 Nacos 时代的内容而非规则本身）。
|
||
- 新增 `patbond-auth/src/test/resources/application.yml`（测试专用配置）：干净检出无 `application.yml` 时 `@SpringBootTest` 仍可启动上下文，`./mvnw clean test` 不依赖复制步骤（已实测：移走本地 yml 后 clean test 依旧 BUILD SUCCESS）。
|
||
- 本机的两个真实 `application.yml` 保留在磁盘（被忽略，不入库），供本地 `spring-boot:run` 使用。
|
||
|
||
**测试（5 新增，共 21 个用例）**
|
||
- `patbond-common/src/test/.../ApiResponseTest.java`（3）。
|
||
- `patbond-user/src/test/.../UserApplicationTests.java`（context loads）+ `UserControllerTest.java`（9：创建成功/重复 409/参数非法 400、verify-password 成功/错密码 401/未知用户 401、getById 200/404、getByUsername 200+404）。
|
||
- `patbond-auth/src/test/.../AuthApplicationTests.java`（context loads）+ `AuthControllerTest.java`（7）：`UserClient` 用 `@MockitoBean` 替换，不依赖 user 进程；按**现状行为**断言（业务失败折叠为 400、FeignException 未翻译逃逸 MVC 层）。
|
||
|
||
**其他**
|
||
- `Readme.md`：重写——技术栈更新、去 Nacos/RabbitMQ、Maven Wrapper 真实启动命令（含 sample→yml 复制步骤）、环境变量表、内存存储现状注记（M4 关闭）。
|
||
- 新增 `mvnw`、`mvnw.cmd`、`.mvn/wrapper/maven-wrapper.properties`。
|
||
- 清理三个模块旧 `target/`（其中 auth/user 的 `target/classes/application.yml` 曾硬编码 `http://patbond.cn:8848/nacos`）；全仓 grep 确认除测试注释中对 ADR-002 的引用外无任何 nacos/8848 残留。
|
||
|
||
## 3. 验收执行记录
|
||
|
||
### 3.1 `JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test`
|
||
|
||
```
|
||
[INFO] Tests run: 3, ... -- in com.patbond.patbond.common.response.ApiResponseTest
|
||
[INFO] Tests run: 1, ... -- in com.patbond.patbond.user.UserApplicationTests
|
||
[INFO] Tests run: 9, ... -- in com.patbond.patbond.user.controller.UserControllerTest
|
||
[INFO] Tests run: 7, ... -- in com.patbond.patbond.auth.controller.AuthControllerTest
|
||
[INFO] Tests run: 1, ... -- in com.patbond.patbond.auth.AuthApplicationTests
|
||
[INFO] patbond-api ........................................ SUCCESS
|
||
[INFO] patbond-common ..................................... SUCCESS
|
||
[INFO] patbond-user ....................................... SUCCESS
|
||
[INFO] patbond-auth ....................................... SUCCESS
|
||
[INFO] BUILD SUCCESS
|
||
```
|
||
|
||
合计 **21 个测试，0 失败 0 错误**（B1 的"0 测试空转"状态解除）。
|
||
首轮曾失败：`@PathVariable` 参数名反射不可用——Boot 3.2+ 行为变化，已在父 pom 加 `-parameters` 修复后全绿。
|
||
补充验证：临时移走两个本地 `application.yml`（模拟干净检出）后重跑 `clean test`，仍 BUILD SUCCESS——测试不依赖被忽略的本地配置。
|
||
|
||
### 3.2 干净配置启动验证（真实进程，验证后已全部停止）
|
||
|
||
`./mvnw -pl patbond-common install` 后两个服务分别 `spring-boot:run`：
|
||
|
||
```
|
||
Tomcat started on port 8082 ... Started UserApplication in 1.691 seconds
|
||
Tomcat started on port 8081 ... Started AuthApplication in 1.789 seconds
|
||
```
|
||
|
||
端到端冒烟（auth 经静态 URL Feign 调 user）：
|
||
|
||
```
|
||
POST /auth/register → {"code":0,...,"userId":1,"username":"smoketest",...}
|
||
POST /auth/login → {"code":0,...,"accessToken":"5c44a5d3...",...}
|
||
POST /auth/login（错密码） → HTTP 500 ← 已知问题，见 4.1
|
||
GET /internal/users/1（8082） → {"code":0,...,"username":"smoketest",...}
|
||
```
|
||
|
||
验证后进程已终止，`ss` 确认 8081/8082 端口释放，无遗留后台进程。
|
||
|
||
注意事项：单独 `-pl` 启动前必须先 `install` patbond-common，否则会从 `~/.m2` 拿到旧快照（首次启动失败正是踩到旧 common 里的 nacos 依赖）；README 启动步骤已包含该命令。
|
||
|
||
## 4. 遗留问题（均为计划内后续工单，非本次回归）
|
||
|
||
1. **错误状态码折叠（审计 M1）**：user 返回的 401/409 经 Feign 变成 auth 侧 500/400。`AuthControllerTest.loginPropagatesFeignExceptionUnhandled` 已把现状钉死为基线，统一异常契约工单动工时该测试会按新契约改写。
|
||
2. **B2 三件套未动**：内存用户存储、不可验证 token、`/internal/**` 无访问控制——属数据库/JWT 后续工单，本次仅在 README 中如实标注。
|
||
3. **无 CI 配置（审计 M3 后半）**：Wrapper 已就位，`./mvnw clean test` 已可作为门禁命令，但 CI 载体（如 GitHub Actions）仍缺。
|
||
4. `AuthTokenResponse.expiresAt` 仍为无时区 `LocalDateTime`，不符 ISO 8601 约定，随 token 重构一并处理。
|
||
5. 旧 common 快照仍在本机 `~/.m2`，已被本次 install 覆盖；其他开发机拉取后需重新 `./mvnw -pl patbond-common install`。
|