# Java → Go：逐项迁移与边界

前一站：[数据模型](data-model.md) · 下一站：[安全与会话](security.md)

## 本次重构的范围

原目录 `D:\xiaolanshu` 保留。新目录 `D:\xiaolanshu-go` 是可以独立启动的实现，业务通过同一 Go 进程完成。重构保留用户可操作的主要功能与前端请求数据结构，同时主动改变部署架构。没有把所有 Java 类翻译成同名 Go 文件，也没有保留依赖 Nacos 的空壳服务。

## 原模块去向

| 原模块/能力 | Go 中的位置 | 差异与理由 |
| --- | --- | --- |
| gateway 路由/认证入口 | httpapi/server.go route、aliases、headers、限流 | 单服务路由，无需服务发现或负载均衡 |
| auth 验证码、注册、密码、退出 | service/auth.go、sessions | JWT 签名 + 可撤销持久会话；开发验证码明确返回 |
| user 用户资料、头像 | service/users.go、httpapi/uploads.go | 真实头像 URL 持久化，忽略伪造操作者 userId |
| 管理员统计和账户管理 | service/admin.go | SQLite 统计、黑名单/软删除、会话撤销、审计事务 |
| note 发布、详情、更新、删除、私密、置顶 | service/notes.go | 正文和元数据在同库保存，增加恢复公开接口 |
| note 点赞和收藏 | note_likes、collections | 关系行唯一，取消幂等，过滤不可见对象 |
| user-relation 关注、粉丝和列表 | service/users.go Follow/Relations | 有方向关系，禁止自己关注自己，SQL 分页 |
| comment 发布、回复、列表、赞、删 | service/comments.go | 同笔记回复校验，根评论删除级联软删回复 |
| count 各种聚合数 | 详情/profile/dashboard 中 SQL | 无单独缓存计数副本，不需要 MQ 更新计数 |
| kv 笔记和评论正文 | notes.content、comments.content | 不再通过 Cassandra RPC；随业务事务写入 |
| oss MinIO/阿里云上传抽象 | uploads.go + 本地 uploads | 已实现本地持久上传；云对象存储为后续适配，不宣称仍支持原双云策略 |
| distributed-id Leaf/雪花 | SQLite INTEGER PRIMARY KEY | 单库安全整数，不能当分布式雪花生成服务使用 |
| search 笔记/用户过滤排序 | SearchNotes、SearchUsers | SQL 子串搜索；无 ES 分词、相关性评分与高亮 HTML |
| search 文档重建 | 同库实时查询、maintenance/check | 没有独立搜索文档，所以无需创建无效重建任务 |
| data-align、Canal、XXL-JOB | 同库关系约束和维护检查 | 单数据库没有跨库异步对齐；外键与完整性检查可实际执行 |
| Nacos、Feign | 函数调用和环境配置 | 没有服务发现网络成本；进程失败影响整个后端 |
| RocketMQ/Lua/布隆过滤器 | 唯一约束、事务和参数化查询 | 达成当前幂等/一致性目的；不复制中间件吞吐与缓存功能 |
| Sentinel | 进程内请求限流、超时、标准 HTTP 限制 | 当前无跨节点配额或熔断控制面 |
| 公共 starter 日志/JSON/异常 | slog、encoding/json、domain.Error | 明确错误码、统一响应；不输出数据库错误给用户 |

原先只供服务互调的 register/findByIds/KV/count/ID 等 RPC 不作为新项目浏览器公共 API 暴露。它们的业务用途合并进上述函数与同库 SQL，避免给访客留下可随意写正文或生成内部数据的接口。对接 Java 内部 RPC 的第三方程序需按新 API 重新适配，兼容性只覆盖原前端业务契约及网关别名。

## 前端接口兼容

规范地址为 `/api/...`，旧的 `/gateway/...` 和旧代理剥去前缀后的路径有别名；搜索还接受 `/search-service/search/...`，上传接受 `/oss-service/file/upload`。新前端只使用规范地址，同一个后端不再分三个 target 端口。

原统一响应 `{success,data,...}` 保留；分页统一为业务 data 中的 `{data,pageNo,totalCount,pageSize,totalPage}`。管理员分页不再依赖旧的特例响应平铺。旧 JWT 签名、发行者和会话表不兼容，迁移后所有用户重新登录是设计结果。

## 已有数据库迁移步骤

本次没有给出原服务实际数据库连接和可验证的数据快照，因此**没有自动导入旧数据，也未修改原库**。原源码包含中间件配置，不能据此假定某台机器上的真实业务库可被安全迁走。需要迁已有数据时按以下顺序：

1. 先确定所有原数据库/正文 KV/对象存储来源，冻结演练快照，保留回滚副本。
2. 导出用户、笔记元数据、正文、评论、关系与上传对象清单，统一 UTF-8 和 UTC。
3. 创建 `legacy_user_id → new_user_id`、note/comment ID 映射；超大 Snowflake 必须映射或全链路改成字符串，禁止浮点强转。
4. 导入用户，再笔记、评论根、评论回复，最后关系。ID 映射同时更新作者、parent_id、reply_id、点赞/收藏指向。
5. 旧 BCrypt 若算法和成本兼容可校验后保留；不可验证格式要求用户重置密码，不能把旧哈希当新明文再哈希一遍。
6. 合并各处正文并核对条数/摘要，复制对象并更新 URL；当前本地上传只支持公开随机直链。
7. 在独立 Go 数据目录检查行数、去重、外键、私密、软删、计数和抽样文件可读性。
8. 演练重新登录、双账号完整生命周期，确认旧系统只读切换窗口与回滚条件，再切流量。

这一过程是待拥有真实快照后执行的迁移方案，不是本次已经跑过的结果。不要把源码重构完成等同于生产数据迁移完成。

## 扩展是否必要

如果目标重新变成多实例高并发，优先根据真实数据量与负载设计 PostgreSQL、共享对象存储、共享会话/限流、事务 outbox 和搜索副本；然后用故障与重启测试证明协议。当前实现能直接用来学习所有业务流程，不能借用原架构图声称拥有未经验证的分布式特性。
