山海万灵 HarmonyOS 文化知识实战（18）：Spring Boot 六服务的业务闭环与健康回读

一次探索会同时触碰神兽内容、地域进度、展厅陈列、护照印章和数字馆长。若这些数据只靠页面临时拼接收藏成功、首页继续探索和馆长讲解很容易各自演化最终出现“内容已更新、进度没更新”或“同一神兽在不同页面名称不一致”的问题。山海万灵将这条链路拆为内容、博物馆、世界、用户、AI 与 CMS 六个 Spring Boot 服务。拆分的目标不是把接口数量做大而是让每类业务数据有唯一归属让调用失败可以被识别、回退和恢复。六个服务各自守住什么服务领域职责对外结果内容服务神兽档案、首页投影、来源与资产图鉴、详情、首页继续探索所需的内容投影世界服务地域目录与神兽归属地域卡片、地域详情和关联神兽集合博物馆服务展厅、主题与展品归属展厅卡片、展厅详情和展品集合用户服务发现记录、护照印章、成长概览幂等的发现结果与可回读的用户概览AI 服务馆长讲解、推荐与语音编排带来源节点和降级状态的讲解结果CMS 服务内容审核、版本、发布任务与审计可追踪的审核流、发布任务和回滚入口边缘网关只接受白名单路由并做首页聚合它不拥有内容、进度或审核数据。这样一来端侧只消费统一响应不需要知道某条信息来自哪张表、缓存还是模型 Provider。首页投影与用户进度如何合并内容服务先提供稳定的首页投影当前地域、展厅、推荐神兽与提示语。用户服务负责把发现记录和护照印章映射为概览网关再把两者合并为端侧需要的首页数据。内容与进度不共享写模型减少“更新一处、另一处遗漏”的风险。GetMapping(/bootstrap) public ApiResponseHomeBootstrap bootstrap() { HomeProjection projection catalogService.homeProjection(); Beast featured catalogService.beast(projection.featuredBeastId()) .orElseThrow(() - new IllegalStateException( home projection references an unpublished beast)); return ApiResponse.success(new HomeBootstrap( new ContinueExplore(region, hall, projection.notice()), List.of(beast), List.of(hall), new ProfileOverview(List.of(), List.of()))); }这里的关键约束是首页投影引用的神兽必须处于可读取状态。引用不存在或尚未公开时服务直接拒绝不完整投影而不是让端侧拿到半截数据再猜测如何展示。发现事件为什么要返回完整概览用户服务把“发现神兽”作为明确命令处理。写入完成后响应同时带回本次发现结果、是否首次创建以及最新概览端侧不必靠乐观累加来猜测经验值或发现数量。PostMapping(/collection/discoveries) public ApiResponseDiscoveryResult createDiscovery( RequestBody DiscoveryRequest request) { UserProgressApplicationService.DiscoveryResult result progressService.createDiscovery(request.beastId(), request.sourceScene()); return ApiResponse.success(new DiscoveryResult( toDiscovery(result.discovery()), result.created(), toProfileOverview(result.overview()))); }同一个发现动作再次到达时业务层保持既有记录并返回createdfalse。调用方可以安全重试概览也不会因为网络重放而多加一条发现或重复发章。地域、展厅与图鉴不通过共享表耦合地域服务回答“某个区域有哪些神兽、进度如何”博物馆服务回答“某个展厅展示什么、属于哪个地域”内容服务回答“神兽本身有哪些可读内容”。三类查询通过稳定 ID 关联而不是让任一服务跨库读写对方的数据。GetMapping(/{regionId}) public ApiResponseRegionCard detail(PathVariable String regionId) { return catalogService.region(regionId) .map(item - ApiResponse.success(card(item))) .orElseGet(() - ApiResponse.failed( WORLD.REGION_NOT_FOUND, region not found or unpublished, )); }这个分工让内容扩充与地域规则演进可以独立发布。某个地域尚未准备好时调用方拿到的是明确错误码不会把空数组误当成“已经探索完成”。AI 与 CMS 放在主链路的哪一侧AI 服务只接收节点类型、节点标识和场景输出讲解内容、来源节点、推荐关系、缓存命中与降级状态。模型地址、密钥和 Provider 选择都留在服务端端侧不会直连模型。CMS 服务则管理审核、版本比对、发布任务、下线与回滚把“可阅读内容”与“可编辑草稿”分开。场景处理方式保护的结果AI Provider 超时或输出不合格返回结构化降级结果并保留安全状态页面仍可说明当前节点不把异常文本写入缓存内容版本未通过审核CMS 不创建可执行发布结果未确认资料不会混入公开目录下游服务不可达网关返回可识别的不可用结果端侧进入既有本地回退不把旧缓存伪装成最新远程数据重复发现请求用户服务返回既有发现与最新概览发现数量、经验和印章不重复增长六服务健康回读本机集成环境启动后用户、内容、博物馆、世界、AI 与 CMS 六个服务的健康接口均返回 HTTP 200。该回读同时确认了服务进程能够连接本地依赖并完成各自的启动初始化。健康检查只回答“进程是否已经具备服务能力”不能替代业务接口的验收。因此网关把健康结果作为路由前的可观测信号而把目录读取、发现写入和审核发布留在各自的业务合同中。这样当一个服务尚未就绪时运维能看到准确的服务名当服务已就绪但业务数据不满足条件时调用方仍能收到领域错误码而不是被一个笼统的 500 掩盖。record ServiceHealth(String service, boolean ready, String detail) {} ListServiceHealth collectHealth(ListHealthClient clients) { return clients.stream() .map(client - client.readHealth() .map(message - new ServiceHealth(client.name(), true, message)) .orElseGet(() - new ServiceHealth(client.name(), false, unavailable))) .toList(); } boolean allReady(ListServiceHealth results) { return results.stream().allMatch(ServiceHealth::ready); }六个服务采用相同的响应封装但各自保留独立的路由前缀。下面是 AI 与 CMS 两个真实端点的最小实现其他领域服务沿用同一契约避免网关和运维脚本为每个服务维护不同的健康响应格式。RestController RequestMapping(/api/v1/ai) public class AiHealthController { GetMapping(/health) public ApiResponseString health() { return ApiResponse.success(ai-service gateway ready); } } RestController RequestMapping(/api/v1/cms) public class CmsHealthController { GetMapping(/health) public ApiResponseString health() { return ApiResponse.success(cms-service ready); } }健康合同也有对应的 Web 层测试。测试不依赖浏览器页面而是直接校验 HTTP 状态与响应中的就绪文本当路由、响应包装或启动配置被改动时回归会立即指出受影响的服务。WebMvcTest({CmsAdminController.class, CmsHealthController.class}) class CmsAdminControllerWebTest { Autowired private MockMvc mockMvc; Test void exposesCmsHealthContract() throws Exception { mockMvc.perform(get(/api/v1/cms/health)) .andExpect(status().isOk()) .andExpect(jsonPath($.success).value(true)) .andExpect(jsonPath($.data).value(cms-service ready)); } } WebMvcTest({RegionCatalogController.class, WorldHealthController.class}) class RegionCatalogControllerWebTest { Autowired private MockMvc mockMvc; Test void exposesTheWorldServiceHealthContract() throws Exception { mockMvc.perform(get(/api/v1/world/health)) .andExpect(status().isOk()) .andExpect(jsonPath($.data).value(world-service ready)); } }回读层级请求对象成功时的含义失败后的处理服务健康六个/health端点对应 Spring Boot 进程已完成启动标记该领域不可用不把请求转成空数据业务读取图鉴、地域、展厅目录返回的内容满足各自查询合同保留错误码和可恢复入口业务写入发现记录、CMS 审核或发布任务持久化结果可由后续查询回读依靠幂等键或任务状态避免重复提交对于端侧而言这种区分直接影响提示方式。健康检查失败时应用应保留已有可读内容并标记远端能力暂不可用业务查询返回“未发布”或“地域不存在”时则应展示与该领域对应的空态或错误说明。两种情况都不能被简单合并成加载失败否则用户既无法判断是否可以重试也无法知道是否需要切换探索目标。服务边界清晰后客户端可以把恢复入口放在真正能够恢复的层级而不是让每个页面各自猜测网络和数据状态。验证时可以按以下顺序观察先读取六个健康结果再请求地域、展厅和图鉴目录随后提交一次发现并确认第二次提交不新增记录最后模拟某个上游不可达确认网关返回可识别错误且端侧回退不白屏。每一步都对应一个明确服务边界出现异常时能够定位到负责的领域而不是在页面层盲目重试。结语六服务的价值在于把内容可信度、用户进度、世界关系、展厅陈列、AI 讲解和运营发布各自放在可测试、可恢复的边界内。端侧仍以统一响应消费数据服务端则通过持久化、错误码、审核流与健康检查维持主链路的可观测性。端侧接入网络与数据状态时可结合 HarmonyOS 应用开发概览 规划页面状态与服务合同的映射。Spring Boot 的配置、健康与生产部署可以参考 Spring Boot Reference Documentation。