Miaohong Java 后端

概述

使用本技能可在 miaohong-cloud-base 项目中高效开展工作，无需每次重新梳理代码库结构。仅加载当前任务所需的参考文档，确保上下文聚焦、简洁。

仓库根目录下的文件 CLAUDE.md 是本项目的首要编码规范。当任何旧有仓库习惯或本技能与 CLAUDE.md 冲突时，一律以 CLAUDE.md 为准。

工作流程

1. 编辑前确认作用范围。
   • 生成或评审后端代码时，优先加载仓库根目录的 CLAUDE.md。
   • 使用 references/module-map.md 进行仓库导航。
   • 使用 references/commands.md 查阅构建、运行及验证命令。
   • 实现或重构代码时，参考 references/conventions.md。
   • 新增或修改 Controller 接口时，参考 references/controller-style.md。
   • 新增或修改 Feign Provider 合约或 Provider 实现时，参考 references/provider-style.md。
   • 新增 Mapper 方法或 XML SQL 时，参考 references/mapper-xml-style.md。
   • 处理失败、校验或错误传播逻辑时，参考 references/exception-style.md。
   • 排查启动、Nacos、网关或 Mapper 相关问题时，参考 references/troubleshooting.md。
2. 始终基于源码工作，而非生成产物。
   • 优先操作 src/main 和 src/test 下的文件。
   • 除非明确需检查构建产物，否则忽略 target/ 目录。
3. 尽可能缩小变更范围。
   • 推荐使用带 -pl -am 参数的定向 Maven 构建。
   • 仅在模块边界不清晰时，才回退至全仓构建。
4. 将配置视为本地文件与 Nacos 的组合。
   • bootstrap.yml 通常定义应用名称、激活 Profile 占位符及 Nacos 配置导入。
   • application.yml 通常承载本地覆盖配置，例如日志、静态资源或模块特定行为。
5. 当行为变更跨越多个服务时，需确认变更所处的正确层级。
   • 共享基础设施应置于 miaohong-common 中。
   • 共享 API 合约及面向 Feign 的 DTO 应置于 miaohong-modules-api 中。
   • 运行时业务逻辑应置于具体服务模块中，如 miaohong-modules、miaohong-auth 或 miaohong-gateway。

仓库专属守则

• 默认要求 Java 17 与 Maven。
• 默认运行时配置依赖于可访问的 Nacos 命名空间及已导入的配置集。
• 业务模块采用“包优先”（package-first）结构，例如 com.miaohong.ai.user，而非将所有功能集中于单一 controller 目录树下。
• 注意 Mapper XML 文件的位置：本仓库将大量 *Mapper.xml 文件存放于 src/main/java/.../mapper/xml，而非 src/main/resources 下，请务必同步检查对应 Java 包旁的 XML 文件。
• 当请求涉及外部或共享合约变更时，编辑前须同时检查提供方模块（provider module）及相关 API 模块。
• Controller 接口文档优先使用方法上方的 Javadoc 注释，**不添加 Swagger 注解**。
• 关于请求与响应结构，请以 CLAUDE.md 为唯一权威依据：
  • 禁用 @PutMapping
  • 禁用 @DeleteMapping
  • 禁用 @PathVariable
  • POST 请求统一使用 @RequestBody DTO
  • GET 请求仅限单参数查询
  • 禁止请求体或响应载荷使用 Map 类型
• 本仓库中生成的 Java 类，作者信息统一标注为 @author bianruhao。
• 服务实现中，应避免服务间循环依赖。优先提取共用逻辑、复用 Mapper/Provider，或将横切关注点迁移至共享模块；禁止通过相互注入形成服务循环依赖。

参考文档索引

• references/module-map.md：根模块、运行时服务、入口点，以及开始排查的位置
• references/commands.md：本仓库专用的定向 Maven 构建、测试与运行命令
• references/conventions.md：从当前代码库推导出的编码规范与模块边界规则
• references/controller-style.md：Controller 类设计、路由、权限控制、日志与响应模式
• references/provider-style.md：面向 Feign 的 Provider 接口与实现模式，含 agent-module 使用指引
• references/mapper-xml-style.md：Mapper 接口与 MyBatis XML 的职责划分
• references/exception-style.md：业务异常、Controller 快速失败（fail-fast）及错误传播规则
• references/troubleshooting.md：Nacos、网关、启动及 Mapper 的调试检查清单