深入解析｜Cursor编程实践经验分享

# 目标请你深入分析当前代码库，生成项目梳理文档。
# 要求1. 你生成的项目梳理文档必须严格按照项目规则中的《项目文档整理规范》来生成。（在rules使用不规范的情况下可以明确指出）
# 输出请你输出项目梳理文档，并放到项目的合适位置。（梳理的文档要落到规定的位置,eg:.cursor/docs中）

# 目标请你根据需求文档，生成技术方案。注意你只需要输出详细的技术方案文档，现阶段不需改动代码。（此时需求文档已经以文档的形式放到了我们的项目中）
# 背景知识为了帮助你更好的生成技术方案，我已为你提供：（1）项目代码（2）需求文档：《XX.md》（上下文@文件的方式给到也可以）（3）项目理解文档:《XX.md》（上下文@文件给到也是同样的效果）
# 核心任务## 1. 文档分析与理解阶段  在完成方案设计前完成以下分析：  - 详细理解需求：    - 请确认你深刻理解了《需求.md》中提到的所有需求描述、功能改动。    - 若有不理解点或发现矛盾请立即标记并提交备注。  - 代码架构理解：    - 深入理解项目梳理文档和现有代码库的分层结构，确定新功能的插入位置。    - 列出可复用的工具类、异常处理机制和公共接口（如`utils.py`、`ErrorCode`枚举类）。 ## 2. 方案设计阶段请你根据需求进行详细的方案设计，并将生成的技术方案放置到项目docs目录下。该阶段无需生成代码。
# 要求1. 你生成的技术方案必须严格按照项目规则中的《技术方案设计文档规范》来生成，并符合技术方案设计文档模板。
# 输出请你输出技术方案，并将生成的技术方案放到项目的合适位置，无需生成代码。

# 目标请你按照设计好的方案，生成代码。
# 背景知识为了帮助你更好的生成代码，我已为你提供：（1）项目代码（2）需求文档：《XX.md》（3）技术方案：《XX.md》（4）项目理解文档:《XX.md》
# 核心任务## 1. 文档分析与理解阶段  在动手编写代码前完成以下分析：  - 需求匹配度检查：    - 深入理解需求文档和方案设计文档，确认《方案设计.md》与《需求.md》在功能点、输入输出、异常场景上的完全一致性。    - 若发现矛盾请立即标记并提交备注。  - 代码架构理解：    - 深入理解项目梳理文档和现有代码库的分层结构，确定新功能的插入位置。    - 列出可复用的工具类、异常处理机制和公共接口（如`utils.py`、`ErrorCode`枚举类）。  
## 2. 代码生成阶段如果你已明确需求和技术方案，请你完成代码编写工作。
# 要求1. 你必须遵循以下核心原则：（1）你生成的代码必须参考当前项目的代码风格。（2）如项目已有可用方法，必须考虑复用、或在现有方法上扩展、或进行方法重载，保证最小粒度改动，减少重复代码。2. 你生成的代码必须符合《Java统一开发编程规范》中定义的规范。
# 输出请你生成代码，并放到代码库的合适位置。

# 任务请你为《xx.go》文件生成单测。
# 要求1. 你生成的单元测试代码必须参考当前项目已有的单测方法风格。
# 示例（从你当前项目中复制一个写好的单测作为提示给大模型的示例）

---description: 此规则适用于go项目的开发规范，技术方案设计文档的编写保证核心代码符合规范，写代码遵守该规范，确保开发质量和效率。globs:alwaysApply: false---# Go项目开发规范## 项目结构规范- 采用领域驱动设计(DDD)分层架构，明确划分为以下层次：  - `controller` 层：处理 HTTP 请求，参数验证，路由转发  - `logic` 层：实现核心业务逻辑，协调各个组件和服务调用  - `model` 层：数据访问和持久化，定义数据结构  - `framework` 层：基础设施和通用工具  - `hsf` 层：服务调用接口定义和实现- **依赖方向**  - 严格遵循依赖方向：controller → logic → model  - 禁止循环依赖  - 上层模块不能依赖于下层模块实现细节，应通过接口进行依赖## 编码规范### 命名约定- **包名命名**  - 使用小写单词，不使用下划线或混合大小写  - 使用简短、具有描述性的名称  - 例如：`model`、`controller`、`logic`- **文件命名**  - 使用小写字母，使用下划线分隔单词  - 例如：`user_service.go`、`order_model.go`- **变量命名**  - 使用驼峰命名法  - 局部变量使用小驼峰（`userID`）  - 全局变量使用大驼峰（`UserService`）  - 常量使用全大写，下划线分隔（`MAX_RETRY_COUNT`）- **接口和结构体命名**  - 使用大驼峰命名法  - 接口名应以 "er" 结尾表示行为，如 `Reader`、`Writer`  - 避免使用 "I" 前缀表示接口### 代码组织- **结构体字段顺序**  - 首先是导出字段，然后是非导出字段  - 相关字段应分组在一起- **函数声明顺序**  - 先声明类型和常量，然后是变量  - 接着是初始化函数（`init()`）  - 最后是其他方法，按重要性或调用关系排序- **import 声明**  - 将 import 分组为标准库、第三方库和内部包  - 组之间用空行分隔  - 使用 goimports 自动排序```goimport(    "context"    "fmt"    "time"    "github.com/gin-gonic/gin"    "github.com/pkg/errors"    "amap-aos-activity/framework/mlogger"    "amap-aos-activity/model/base")```## 错误处理规范- **使用项目标准错误类型**  - 使用 `common.Error` 统一封装业务错误  - 保持错误码和错误信息的一致性- **错误传播**  - 在逻辑层中，使用 `errors.Wrap` 包装错误以保留堆栈信息  - 谨慎处理空指针和边界情况- **错误日志记录**  - 只在错误发生的源头记录日志，避免重复记录  - 使用项目统一的日志框架 `mlogger`  - 在记录错误时包含足够的上下文信息```goif err != nil {    tracelogger.XErrorf(ctx, "failed to query data: %v", err)    return nil, common.NewError(common.ErrCodeDB, "数据查询失败")}```## 并发处理规范- **使用 context 进行超时控制**  - 所有长时间运行的操作都应接受 context 参数  - 及时检查和响应 context 取消信号- **并发安全**  - 使用 mutex、atomic 或 channel 来保护共享资源  - 避免 goroutine 泄漏，确保所有 goroutine 都能正确退出  - 使用项目提供的 `errgroup` 包管理并发任务- **资源控制**  - 使用 worker pool 或信号量控制并发数量  - 使用项目提供的框架组件进行异步任务处理## 性能优化规范- **避免不必要的内存分配**  - 预分配已知大小的切片和 map  - 使用 pointer 传递大结构体  - 使用 sync.Pool 复用临时对象- **高效的 IO 操作**  - 使用缓冲 IO  - 批量处理数据库操作  - 实现合理的缓存策略，使用 mcache 或 mredis- **高效的 JSON 处理**  - 使用项目指定的高性能 JSON 库（sonic）  - 对频繁使用的结构体预定义字段标签## 测试规范- **单元测试覆盖**  - 为所有关键业务逻辑编写单元测试  - 使用表驱动测试方法  - 测试文件与被测试文件放在同一目录，使用 `_test.go` 后缀- **模拟外部依赖**  - 使用接口和依赖注入以便于测试  - 使用 mock 框架模拟外部服务和数据库- **基准测试**  - 为性能关键路径编写基准测试  - 使用性能分析工具发现瓶颈## 项目标准组件使用指南- **日志记录**  - 使用 `mlogger` 包进行日志记录  - 在关键流程节点记录日志，但避免过度记录- **配置管理**  - 使用 `mconfig` 包读取配置  - 避免硬编码配置值- **HTTP 客户端**  - 使用 `mhttp` 包进行 HTTP 调用  - 设置合理的超时和重试策略- **缓存使用**  - 使用 `mcache` 或 `mredis` 实现缓存  - 实现合适的缓存失效策略## 代码示例### Controller 层示例```go// controller/example/example.gopackage exampleimport (    "context"    "github.com/gin-gonic/gin"    "amap-aos-activity/framework/mlogger"    "amap-aos-activity/logic/example")// Handler 处理HTTP请求func Handler(c *gin.Context) {    ctx := c.Request.Context()    // 参数解析与验证    var req struct {        UserID string `json:"userId" binding:"required"`    }    if err := c.ShouldBindJSON(&req); err != nil {        mlogger.XWarnf(ctx, "invalid request: %v", err)        c.JSON(400, gin.H{"code": "INVALID_PARAM", "message": "参数不合法"})        return    }    // 调用逻辑层    resp, err := example.ProcessRequest(ctx, req)    if err != nil {        c.JSON(500, gin.H{"code": err.Code, "message": err.Message})        return    }    c.JSON(200, resp)}```### Logic 层示例```go// logic/example/processor.gopackage exampleimport (    "context"    "github.com/pkg/errors"    "amap-aos-activity/basic/common"    "amap-aos-activity/framework/mlogger"    "amap-aos-activity/model/example")// ProcessRequest 处理业务逻辑func ProcessRequest(ctx context.Context, req interface{}) (interface{}, *common.Error) {    // 类型断言    request, ok := req.(struct{ UserID string })    if !ok {        return nil, common.NewError(common.ErrCodeParam, "请求参数类型错误")    }    // 业务逻辑处理    data, err := example.GetUserData(ctx, request.UserID)    if err != nil {        mlogger.XErrorf(ctx, "failed to get user data: %+v", errors.WithStack(err))        return nil, common.NewError(common.ErrCodeService, "获取用户数据失败")    }    // 返回结果    returnmap[string]interface{}{        "userId": request.UserID,        "data": data,    }, nil}```### Model 层示例```go// model/example/user_model.gopackage exampleimport (    "context"    "time"    "github.com/pkg/errors"    "amap-aos-activity/framework/mdb"    "amap-aos-activity/framework/mcache")// UserData 表示用户数据type UserData struct {    UserID    string    `json:"userId" db:"user_id"`    Name      string    `json:"name" db:"name"`    CreatedAt time.Time `json:"createdAt" db:"created_at"`}// GetUserData 从数据库获取用户数据func GetUserData(ctx context.Context, userID string) (*UserData, error) {    // 尝试从缓存获取    cacheKey := "user_data:" + userID    var userData UserData    cached, err := mcache.Get(ctx, cacheKey, &userData)    if err == nil && cached {        return &userData, nil    }    // 从数据库查询    query := "SELECT user_id, name, created_at FROM user_table WHERE user_id = ?"    err = mdb.GetDB().GetContext(ctx, &userData, query, userID)    if err != nil {        return nil, errors.Wrap(err, "query database failed")    }    // 更新缓存    _ = mcache.Set(ctx, cacheKey, userData, 5*time.Minute)    return &userData, nil}```## 示例<example>// 良好实践：正确的错误处理和日志记录package serviceimport (    "context"    "github.com/pkg/errors"    "amap-aos-activity/basic/common"    "amap-aos-activity/framework/mlogger"    "amap-aos-activity/model/user")func GetUserProfile(ctx context.Context, userID string) (*user.Profile, *common.Error) {    // 参数验证    if userID == "" {        return nil, common.NewError(common.ErrCodeParam, "用户ID不能为空")    }    // 调用模型层    profile, err := user.GetProfileByID(ctx, userID)    if err != nil {        // 包装错误并记录日志        wrappedErr := errors.Wrap(err, "获取用户资料失败")        mlogger.XErrorf(ctx, "%+v", wrappedErr) // 记录堆栈信息        // 返回适当的业务错误        if errors.Is(err, user.ErrUserNotFound) {            return nil, common.NewError(common.ErrCodeNotFound, "用户不存在")        }        return nil, common.NewError(common.ErrCodeService, "获取用户资料失败")    }    return profile, nil}</example><example type="invalid">// 不良实践：不规范的错误处理和日志记录package serviceimport (    "context"    "fmt"    "log"    "amap-aos-activity/model/user")func GetUserProfile(ctx context.Context, userID string) (*user.Profile, error) {    // 缺少参数验证    // 直接调用模型层    profile, err := user.GetProfileByID(ctx, userID)    if err != nil {        // 错误：使用fmt直接打印错误        fmt.Println("Error getting user profile:", err)        // 错误：使用标准log包而非项目日志框架        log.Printf("Failed to get profile for user %s: %v", userID, err)        // 错误：直接返回底层错误，没有包装或分类        return nil, err    }    return profile, nil}</example>

# 项目文档规范
**文档受众明确为软件开发人员**，目的是帮助开发团队快速理解系统架构、业务逻辑和技术实现细节，便于代码维护、功能扩展和知识传递。## 关键规则- 项目文档必须包含四个核心部分：项目简介、核心领域模型、项目结构和外部依赖- 接口文档必须按照@接口文档规范进行编写和维护- 业务流程文档必须按照@业务流程文档规范进行编写和维护- 文档应保持客观性，基于现有代码而非理想状态- 文档中使用的术语必须与代码中的术语保持一致- 文档应使用Markdown格式，支持图表、表格和代码块- 代码示例必须是从实际代码中提取的，而非虚构的- 图表应使用Mermaid或PlantUML语法，以确保可维护性- 文档应当引用具体的代码文件路径，便于读者查找相关实现- 首先判断项目是否使用GBF框架，并根据实际架构选择适合的文档结构和内容- 所有文档必须统一放置在docs目录下，并使用规定的中文名称- **文档生成过程中必须确保完整覆盖所有内容，不允许任何遗漏**## 文档优化与结构指南- **主索引文档**：每个核心部分创建一个主索引文档，包含子文档链接和简要说明- **文档内导航**：超过500行的文档必须在开头提供目录- **分层结构**：按照"金字塔结构"组织（顶层：核心概念；中层：主要功能模块；底层：具体实现细节）- **文档拆分**：接口超过20个时按业务域拆分；核心实体超过10个时按业务领域拆分## 文档结构和内容要求### 1. 项目简介 - docs/项目概述.md必须包含：项目背景、项目目标、功能概述、技术栈和架构类型（明确是否使用GBF框架）### 2. 核心领域模型 - docs/领域模型说明.md必须包含：- 领域模型概述：核心业务概念的定义和边界- 核心实体关系图：使用E-R图或类图表示- 关键业务场景下的模型交互- 数据流转关系**强制性领域模型扫描规则**：- **全面扫描**：包括`*Entity.java`、`*DO.java`、`*PO.java`、`*Model.java`、`@Entity`、`@Table`、`@Document`注解类、服务层核心模型、DTO/VO类- **按目录结构识别**：位于`model`、`domain`、`entity`目录及其子目录下的Java类文件，以及领域模型专用包路径（如`*.domain.*`、`*.model.*`、`*.entity.*`）下的类文件- **完整提取**：实体属性和业务含义、实体关系、聚合结构、生命周期和状态流转- **识别规则**：属性约束、实体关系约束、状态转换规则**领域模型分析策略**：- 全域扫描实体类和值对象，支持多种ORM框架- 提取关联关系（通过字段类型、泛型参数和ORM注解）- 识别聚合根和聚合边界（通过包结构和类间关系）- 分析继承结构（包括抽象类、接口和实现类）- 提取业务方法和状态转换逻辑- 生成完整属性表和业务规则说明**GBF框架项目补充**：扩展点定义与实现、行业/场景定制点、路由条件与动态选择机制### 3. 接口文档 - docs/接口文档.md接口文档应遵循专门的@接口文档规范进行创建和维护，以确保API接口的完整记录和更新。### 4. 业务流程 - docs/业务流程说明.md业务流程文档应遵循专门的@业务流程文档规范进行创建和维护，以确保业务流程的完整记录和更新。### 5. 项目结构 - docs/项目结构说明.md必须包含：项目模块划分、代码组织结构、关键包说明、分层架构说明**GBF框架项目补充** - docs/GBF框架应用说明.md：GBF分层结构、扩展点文件位置、行业定制目录、场景定制目录### 6. 外部依赖与下游服务 - docs/外部依赖说明.md必须包含：- 下游服务概述：依赖的所有外部服务列表和用途- 调用关系图：系统与外部服务的调用关系## 文档生成工作流程1. **架构识别**：确定项目架构类型、识别关键组件和分层结构2. **代码分析**：识别核心业务包和类、分析领域模型、提取接口定义、理解调用链路3. **内容整理**：按文档结构组织信息、提取代码示例、绘制图表4. **审核完善**：验证文档与代码一致性、补充关键信息、完善图表和示例   - **接口覆盖性验证**：确认总览文档中的所有接口都在详细文档中有完整描述   - **文档完整性检查**：确保没有遗漏任何必要的接口和服务描述5. **定期更新**：与代码审查流程集成、重大变更更新文档、每季度全面审核## 示例### 领域模型示例```markdown## 核心实体关系图```mermaidclassDiagram  classItem {    +Long id    +String name    +BigDecimal price    +String status    +validatePrice()    +changeStatus(String)  }    classTyingRule {    +Long id    +Long mainItemId    +List<Long> subItemIds    +Date startTime    +Date endTime    +enable()    +disable()  }    Item "1" -- "n" TyingRule: 被定义为主商品  TyingRule "1" -- "n" Item: 关联搭售商品```## 实体属性详细说明### Item 商品实体| 属性名 | 类型 | 说明 ||----|---|---|| id | Long | 商品唯一标识 || name | String | 商品名称，长度限制：2-50个字符 || price | BigDecimal | 商品价格，精确到小数点后2位，最小值：0.01 || status | String | 商品状态，枚举值：ON_SHELF(上架)、OFF_SHELF(下架)、DELETED(删除) |#### 业务规则- 商品价格必须大于0- 商品状态只能按特定流程转换（上架->下架->删除）```### 业务流程示例```markdown## 搭售规则创建流程### 核心流程图```mermaidflowchart TD    A[创建请求] --> B{校验参数}    B -->|无效| C[返回错误]    B -->|有效| D[查询主商品]    D --> E{商品存在?}    E -->|否| F[返回错误]    E -->|是| G[查询搭售商品]    G --> H{商品存在?}    H -->|否| I[返回错误]    H -->|是| J[保存规则]    J --> K[返回成功]```### 调用链路**入口点**: `ItemTyingController.createTyingRule()`**调用流程**:1. 请求参数校验 - `validateTyingRequest(request)`2. 查询主商品信息 - `itemService.getItemById()`3. 校验主商品状态 - `validateItemStatus(item)`4. 查询并校验搭售商品列表 - `validateSubItems()`5. 构建并保存搭售规则 - `tyingRuleRepository.save()`6. 发送规则创建事件 - `eventPublisher.publishEvent()`### 关键判断点| 判断点 | 条件 | 处理路径 ||-----|---|----|| 参数校验 | 主商品ID为空 | 返回参数错误 || 主商品校验 | 主商品不存在 | 返回商品不存在错误 || 搭售商品校验 | 存在无效商品 | 返回商品无效错误 |

# 代码分析规则
## 目标根据代码入口深入分析完整业务流程，生成详细的业务流程文档，便于团队理解和维护代码。## 关键规则- **必须生成分析文档保存到项目的docs目录下**- **必须使用sequential-thinking辅助分析**- **必须深入方法内部逻辑，因此你可能需要检索代码**- **建议使用sequential-thinking辅助检索代码**### 1. 聚焦业务核心逻辑- 忽略日志打印、参数基础校验等次要逻辑- 忽略异常处理中的技术细节，只关注业务异常处理逻辑- 忽略与业务无关的工具方法调用（如字符串处理、集合操作等）- 聚焦业务状态转换、流程分支、核心计算等关键逻辑### 2. 深入方法调用链- 追踪每个关键方法的内部实现，不仅停留在方法调用层面- 对调用链上的每个重要方法都分析其内部业务逻辑- 对于外部依赖的服务（如HSF、RPC调用），说明其功能和业务意义- 深入分析每个关键业务分支的条件和处理逻辑### 3. 结合已有文档- 优先使用已有文档中的描述，避免重复分析- 如果已有文档对某个方法有详细描述，直接引用该内容- "站在巨人的肩膀上"，基于已有文档进行补充和完善- 对已有文档与代码实现不一致的地方进行标注### 4. 文档输出规范- 分析结果保存到 `/docs` 目录下，使用 Markdown 格式- 文档命名格式：`业务名称-流程分析.md`（如：`订单创建-流程分析.md`）- 文档需包含方法调用树，清晰展示调用层级关系- 使用分步业务流程描述完整处理过程## 文档结构模板```markdown# 业务名称流程分析## 功能概述[简要描述该业务功能的目的和作用]## 入口方法`com.example.Class.method`## 方法调用树```入口方法├─ 一级调用方法1│  ├─ 二级调用方法1.1│  ├─ 二级调用方法1.2├─ 一级调用方法2   ├─ 二级调用方法2.1   └─ 二级调用方法2.2      └─ 三级调用方法```## 详细业务流程1. [步骤1：业务逻辑描述]2. [步骤2：业务逻辑描述]   - [子步骤2.1：详细逻辑]   - [子步骤2.2：详细逻辑]3. [步骤3：业务逻辑描述]## 关键业务规则- [规则1：描述业务规则及其条件]- [规则2：描述业务规则及其条件]## 数据流转- 输入：[描述方法输入及其业务含义]- 处理：[描述关键数据处理和转换]- 输出：[描述方法输出及其业务含义]## 扩展点/分支逻辑- [分支1：触发条件及处理逻辑]- [分支2：触发条件及处理逻辑]## 外部依赖- 标注对外部系统的依赖## 注意事项- [列出实现中需要特别注意的点]```## 系统交互图- 如果业务流程包含多个系统模块，请使用PlantUML画出时序图## 代码分析技巧### 步骤1：明确业务入口- 确定代码分析的起点（通常是Controller、Facade或Service层的公开方法）- 了解该方法的调用场景和业务背景### 步骤2：构建方法调用树- 从入口方法开始，追踪所有重要的方法调用- 使用缩进表示调用层级，清晰展示调用关系- 忽略非核心方法调用（如日志、参数校验等）### 步骤3：分析业务流程- 按照代码执行顺序分析业务处理步骤- 重点关注业务状态转换和分支逻辑- 提取关键业务规则和数据处理逻辑### 步骤4：整理业务规则- 总结条件判断中隐含的业务规则- 分析不同场景下的处理差异- 提炼业务逻辑的核心决策点### 步骤5：描述数据流转- 分析关键数据的来源、处理和去向- 说明数据模型转换和业务含义- 关注核心业务实体的状态变化## 示例分析参考 [订单查询.md](/docs/订单查询.md) 文档了解完整的分析示例:该示例展示了订单查询业务的完整分析，包括:- 方法调用树展示了完整调用链- 详细业务流程按步骤拆解- 关键业务规则清晰列出- HSF接口等外部依赖明确说明- 特殊处理逻辑如推广通退款按钮透出详细解释## 好的分析的特征1. **完整性**：覆盖所有核心业务逻辑和分支2. **层次性**：清晰展示处理流程的层次结构3. **业务性**：以业务视角描述，而非技术实现细节4. **精确性**：准确反映代码的实际处理逻辑5. **可理解性**：业务人员也能理解的表述方式6. **实用性**：帮助读者快速理解业务流程和规则 

# 技术方案设计文档规范
## 关键规则- 技术方案文档必须遵循规定的章节结构，包括名词解释、领域模型、应用调用关系和详细方案设计四个主要部分- 名词解释部分必须建立业务和技术的统一语言，确保术语简单易懂- 领域模型需清晰表达业务实体及其关系，可使用UML图或ER图进行可视化- 应用调用关系必须体现跨应用的接口调用关系和MQ的生产消费关系- 详细方案设计应按应用和业务流程进行分类，对每个接口的改动点、代码分层和文档变更进行详细说明- 代码改动点需重点突出实现思路，而不仅是罗列代码变更- 对外接口协议的所有变更（包括字段变更等）必须在接口文档中明确体现- 首先明确项目是否使用GBF框架，并选择相应的技术方案设计模板- 使用GBF框架的项目，需明确说明各层级服务规划及扩展点设计- 非GBF框架项目，应明确说明标准分层架构设计## 架构识别与方案适配### 如何判断项目是否使用GBF框架- 代码中存在Process、NodeService、DomainService等类或注解- 存在Ability接口和Action实现类- 包结构中有platform、node、domain、ability等目录- 有明确的扩展点机制和BizCode、Scenario路由### 方案适配策略- 使用GBF框架的项目，技术方案需关注扩展点设计和流程编排- 非GBF框架项目，技术方案关注传统分层设计和接口实现- 在方案开头明确说明项目所使用的架构模式- 根据架构特点选择适当的设计模式和描述方式## 技术方案设计文档模板```markdown# 技术方案设计文档：[方案名称]## 文档信息- 作者：[作者姓名]- 版本：[版本号，如v1.0]- 日期：[创建/更新日期]- 状态：[草稿/已评审/已确认]- 架构类型：[GBF框架/非GBF框架] - 版本：[框架版本号]# 一、名词解释[建立业务和技术的统一语言，尽量简单易懂]| 术语 | 解释 ||------|------|| 术语1 | 含义说明 || 术语2 | 含义说明 |# 二、领域模型[描述业务领域中的核心实体及其关系，推荐使用UML图表示]## 核心实体[列出核心业务实体及其属性、行为]## 实体关系[描述实体间的关系，可使用ER图]```mermaidclassDiagram    Class01 <|-- AveryLongClass : Cool    Class03 *-- Class04    Class05 o-- Class06    Class07 .. Class08    Class09 --> C2 : Where am I?    Class09 --* C3    Class09 --|> Class07    Class07 : equals()    Class07 : Object[] elementData    Class01 : size()    Class01 : int chimp    Class01 : int gorilla    Class08 <--> C2: Cool label```# 三、应用调用关系[体现跨应用的接口调用关系、MQ的生产消费关系]## 系统架构图[系统整体架构图，展示系统组件和交互关系]```mermaidflowchart TD    A[应用1] -->|接口调用| B[应用2]    B -->|消息发送| C[消息队列]    D[应用3] -->|消息消费| C    D -->|数据存储| E[(数据库)]```## 时序图[关键流程的时序图，展示组件间的交互顺序]```mermaidsequenceDiagram    参与者A->>参与者B: 请求数据    参与者B->>参与者C: 转发请求    参与者C-->>参与者B: 返回数据    参与者B-->>参与者A: 处理后返回```# 四、详细方案设计## 架构选型[说明本方案采用的架构模式，如标准三层架构、GBF框架架构等]### 分层架构说明[描述本方案的分层架构，说明各层职责]#### 标准分层架构（非GBF框架项目）```# HTTP接口方式- Controller层：处理HTTP请求，参数校验- Service层：实现业务逻辑- Repository层：数据访问和持久化- Domain层：领域模型和业务规则# HSF/RPC服务方式- Provider层：服务提供者，定义和实现HSF服务接口- Service层：实现业务逻辑- Repository层：数据访问和持久化- Domain层：领域模型和业务规则```### 数据模型设计[描述数据模型的设计，包括不同层次的数据模型]```# 标准数据模型（非GBF框架项目）- DTO(Data Transfer Object)：接口层数据传输对象- BO(Business Object)：业务逻辑层数据对象- DO(Domain Object)：领域模型对象- PO(Persistent Object)：持久化对象# GBF框架数据模型（GBF框架项目）- DTO：对接客户端，透出业务流程结果- DO：封装核心领域逻辑，定义服务入口- PO：与数据库交互，屏蔽存储细节```## 应用1### 业务流程1#### xxx接口**接口说明**：[详细说明接口的用途和功能]**接口路径**：[HTTP方法] [路径] 或 [HSF服务接口定义]**请求参数**：```json{  "param1": "value1",  "param2": "value2"}```**返回结果**：```json{  "code": 200,  "message": "success",  "data": {    "field1": "value1",    "field2": "value2"  }}```#### 接口改动点[说明接口的改动类型：新增、能力调整、扩展等，并详述改动内容]#### 代码分层设计[描述代码的分层结构，确保符合工程规范]##### 标准分层设计（非GBF框架项目）```# HTTP接口方式- Controller层：处理HTTP请求，参数校验  - 职责：参数校验、请求处理、结果封装  - 代码位置：web包、controller包  - 设计要点：保持轻量，不包含业务逻辑- Service层：实现业务逻辑  - 职责：实现业务逻辑、编排服务调用、事务管理  - 代码位置：service包、manager包  - 设计要点：聚合与编排，可包含复杂业务逻辑- Repository层：数据访问和持久化  - 职责：封装数据访问逻辑，实现数据持久化  - 代码位置：repository包、dao包  - 设计要点：封装数据库操作，提供数据访问接口- Domain层：领域模型和业务规则  - 职责：定义领域模型，实现领域规则  - 代码位置：domain包、model包  - 设计要点：领域驱动设计，封装核心业务规则```##### GBF框架分层设计（GBF框架项目）```# Process定义（Platform层）- 职责：编排NodeService，形成完整业务流程- 代码位置：platform包- 设计要点：  - Process作为最上层逻辑，直接承接接口请求  - 通过Spring Bean声明Process流程配置  - Process只能调用NodeService，不能跨层调用  - 不应包含具体业务逻辑，专注于流程编排# NodeService实现（Node层）- 职责：组合多个DomainService，形成标准化服务入口- 代码位置：node包- 设计要点：  - NodeService作为标准化服务入口  - 禁止NodeService之间相互调用  - 通过扩展点控制节点级逻辑(如前置校验)  - 不应包含复杂业务逻辑，主要负责编排# DomainService实现（Domain层）- 职责：提供原子级业务能力- 代码位置：domain包- 设计要点：  - DomainService提供原子级业务能力  - 禁止DomainService之间相互调用  - 依赖扩展点接口实现逻辑分支控制  - 包含特定领域的核心业务逻辑# 扩展点设计（Ability层与App层）- 职责：定义扩展点接口和实现- 代码位置：  - 接口定义：ability包  - 行业实现：app包下对应行业目录  - 场景实现：domain/node包下对应scenario目录- 设计要点：  - 统一在Ability层声明扩展点接口  - 行业定制实现放在App层(如/app/food/)  - 场景定制实现放在Domain/Node包下  - 扩展点必须有默认实现，保证基础功能可用```#### 扩展点设计（GBF框架项目）[详细说明本功能涉及的扩展点设计]```java# 扩展点接口（Ability层）package com.amap.xxx.ability;/** * [扩展点名称]能力 */public interface XxxAbility {    /**     * [方法说明]     * @param request 请求参数     * @return 处理结果     */    Result doSomething(XxxRequest request);}# 扩展点实现路由条件- BizCode：[业务码，如"FOOD"、"RETAIL"]- Scenario：[场景码，如"C2C"、"B2C"]- 优先级规则：  1. 精确匹配（BizCode + Scenario）  2. 按场景降级匹配  3. 使用默认实现# 扩展点默认实现（Ability层）package com.amap.xxx.ability.impl;/** * [扩展点名称]默认实现 */publicclassDefaultXxxActionimplementsXxxAbility {    @Override    public Result doSomething(XxxRequest request){        // 默认实现逻辑        return Result.success();    }}# 扩展点行业定制实现（App层）package com.amap.xxx.app.food;/** * [行业名称][扩展点名称]实现 */@Extension(bizId = "FOOD")publicclassFoodXxxActionimplementsXxxAbility {    @Override    public Result doSomething(XxxRequest request){        // 行业特定实现逻辑        return Result.success();    }}# 扩展点场景定制实现（Domain/Node层）package com.amap.xxx.domain.scenario.b2c;/** * [场景名称][扩展点名称]实现 */@Extension(scenario = "B2C")publicclassB2CXxxActionimplementsXxxAbility {    @Override    public Result doSomething(XxxRequest request){        // 场景特定实现逻辑        return Result.success();    }}```##### 路由条件设计[说明扩展点的路由条件设计]```# 路由维度- 业务维度（BizCode）：区分不同行业，如"FOOD"、"RETAIL"- 场景维度（Scenario）：区分不同场景，如"C2C"、"B2C"- 其他维度：用户类型、渠道等# 路由策略- 优先级1：精确匹配（BizCode=A + Scenario=B）- 优先级2：业务码匹配（BizCode=A）- 优先级3：场景码匹配（Scenario=B）- 优先级4：默认实现# 降级策略如果找不到满足条件的扩展点实现，按优先级顺序降级匹配，直到找到默认实现```#### 代码改动点[详述需要改动的代码，重点说明实现思路]1. Controller/Provider层改动：   - 新增XX控制器/服务提供者   - 修改YY方法参数2. Service层改动：   - 新增XX服务   - 调整YY逻辑处理流程3. GBF框架特定改动(GBF框架项目)：   - 新增Process流程定义   - 新增NodeService节点服务   - 新增扩展点接口与实现   - 修改扩展点路由规则## 数据库变更### 表结构设计[描述需要新增或修改的数据库表结构]#### 表名：[表名]| 字段名 | 数据类型 | 是否为空 | 主键 | 注释 ||-------|---------|---------|------|------|| id | bigint | 否 | 是 | 主键ID || ... | ... | ... | ... | ... |### 索引设计[描述需要新增或修改的索引]| 索引名 | 字段 | 索引类型 | 说明 ||-------|------|---------|------|| idx_xxx | 字段1, 字段2 | 普通/唯一/主键 | 索引说明 |## 接口文档变更[描述需要新增或修改的接口文档]### 接口名：[接口名]- 接口路径：[HTTP方法] [路径] 或 [HSF服务接口定义]- 变更类型：[新增/修改/删除]- 变更说明：[详细说明接口变更]## 配置变更[描述需要新增或修改的配置]### 配置类型：[配置类型]- 配置名：[配置名]- 配置值：[配置值]- 说明：[配置说明]## 非功能性需求### 性能需求[描述性能需求，如响应时间、并发量等]### 可用性需求[描述可用性需求，如系统可用率、故障恢复能力等]### 扩展性需求[描述扩展性需求，如系统的可扩展性、可伸缩性等]## 兼容性与平滑迁移方案[描述系统升级的兼容性问题及平滑迁移方案]### 兼容性问题[描述可能的兼容性问题]### 平滑迁移方案[描述平滑迁移的方案]## 风险与应对措施[描述可能的风险及应对措施]| 风险 | 可能性 | 影响 | 应对措施 ||------|-------|------|---------|| 风险1 | 高/中/低 | 高/中/低 | 应对措施1 || 风险2 | 高/中/低 | 高/中/低 | 应对措施2 |```## 示例### 非GBF框架项目技术方案示例<example>## 代码分层设计### 添加商品API的实现结构如下：```# Controller层- com.amap.mall.web.controller.ProductController  - 职责：接收HTTP请求，校验参数，调用Service层，封装返回结果  - 主要方法：addProduct(AddProductRequest request)# Service层- com.amap.mall.service.ProductService (接口)- com.amap.mall.service.impl.ProductServiceImpl (实现)  - 职责：处理业务逻辑，调用Repository层，实现事务控制  - 主要方法：addProduct(ProductDO product)# Repository层- com.amap.mall.repository.ProductRepository (接口)- com.amap.mall.repository.impl.ProductRepositoryImpl (实现)  - 职责：封装数据访问逻辑，调用DAO层  - 主要方法：insert(ProductPO product)# DAO层- com.amap.mall.dao.ProductDAO  - 职责：与数据库交互，执行SQL  - 主要方法：insert(ProductPO product)```根据上述设计，添加商品功能的调用链为：1. 客户端调用ProductController.addProduct()2. Controller校验参数并调用ProductService.addProduct()3. Service处理业务逻辑并调用ProductRepository.insert()4. Repository转换对象并调用ProductDAO.insert()5. DAO执行SQL插入数据</example>### GBF框架项目技术方案示例<example>## GBF框架分层设计### 添加搭售规则功能的实现结构如下：```# Process层（Platform层）- com.amap.mall.tying.platform.CreateRuleProcess  - 职责：定义搭售规则创建流程，编排NodeService调用顺序  - 流程节点：参数校验 -> 商品信息获取 -> 规则冲突检查 -> 规则持久化# NodeService层（Node层）- com.amap.mall.tying.node.ValidateRuleNodeService  - 职责：实现规则参数校验节点  - 使用扩展点：RuleValidateAbility（规则校验能力）- com.amap.mall.tying.node.CheckConflictNodeService  - 职责：实现规则冲突检查节点  - 使用扩展点：ConflictCheckAbility（冲突检查能力）- com.amap.mall.tying.node.PersistRuleNodeService  - 职责：实现规则持久化节点  - 使用扩展点：RulePersistAbility（规则持久化能力）# DomainService层（Domain层，可选）- com.amap.mall.tying.domain.service.ItemInfoDomainService  - 职责：获取商品信息的原子能力服务  - 使用扩展点：ItemInfoAbility（商品信息获取能力）# Ability层（扩展点接口定义）- com.amap.mall.tying.ability.RuleValidateAbility  - 职责：定义规则校验的扩展点接口  - 方法：validate(RuleRequest request)- com.amap.mall.tying.ability.ConflictCheckAbility  - 职责：定义冲突检查的扩展点接口  - 方法：check(RuleRequest request)# App层（行业定制实现）- com.amap.mall.tying.app.food.FoodRuleValidateAction  - 职责：实现食品行业特定的规则校验逻辑  - 路由条件：@Extension(bizId = "FOOD")- com.amap.mall.tying.app.retail.RetailRuleValidateAction  - 职责：实现零售行业特定的规则校验逻辑  - 路由条件：@Extension(bizId = "RETAIL")# 默认实现（Ability层实现）- com.amap.mall.tying.ability.impl.DefaultRuleValidateAction  - 职责：实现默认的规则校验逻辑  - 应用场景：当不满足任何行业/场景定制条件时```扩展点路由设计：1. 按业务码（bizId）路由：不同行业的定制实现   - FOOD -> FoodRuleValidateAction   - RETAIL -> RetailRuleValidateAction2. 按场景码（scenario）路由：不同场景的定制实现   - B2C -> B2CRuleValidateAction   - C2C -> C2CRuleValidateAction3. 精确匹配：同时匹配业务码和场景码   - FOOD + B2C -> FoodB2CRuleValidateAction4. 降级策略：找不到匹配的实现时，使用默认实现   - 默认 -> DefaultRuleValidateAction</example><example type="invalid">## 技术方案设计我们将实现一个新的搭售规则管理功能。开发计划：1. 添加新的Controller处理HTTP请求2. 添加新的Service处理业务逻辑3. 添加新的DAO访问数据库（错误原因：没有明确说明项目使用的架构类型，缺乏分层设计的详细说明，没有明确接口定义和实现方式，对于GBF项目没有说明扩展点设计）</example>## 方案设计工作流程1. **架构识别阶段**   - 确定项目使用的架构类型(GBF/非GBF)   - 识别关键架构组件和分层结构   - 确定方案设计重点和特殊要求   - 选择适合的方案模板2. **需求分析阶段**   - 确定功能边界和核心业务流程   - 识别核心业务实体和领域模型   - 确定接口定义和数据结构   - 识别可能的扩展点和变化点3. **方案设计阶段**   - 根据架构特点进行分层设计   - 确定接口实现和组件交互   - 设计数据库结构和索引   - 对于GBF项目，设计扩展点和路由规则4. **方案评审阶段**   - 验证方案与架构的一致性   - 验证功能覆盖度和完整性   - 评估技术风险和性能问题   - 确保方案文档结构清晰、内容完整

---description: `此规则适用于go项目的单元测试开发规范，Go单元测试提供全面指南，规范测试结构、mock技术和断言方法，确保测试代码质量与可维护性。`globs:alwaysApply: false---# 中间件客户端调用规范## 关键规则- **所有HTTP和HSF等中间件客户端必须放在framework/client目录下**- **必须遵循统一的命名规范：服务功能+Service命名方式**- **必须使用Context作为第一个参数，支持分布式追踪和日志记录**- **中间件客户端必须从配置中心读取配置，不允许硬编码**- **中间件调用必须记录完整的请求和响应日志**- **必须实现统一的错误处理和返回机制**- **应对关键调用实现缓存机制，减少直接调用次数**- **请求和响应结构体必须实现JavaClassName方法（HSF特有）**- **HSF服务必须在init方法中注册模型**- **客户端调用需要进行合理的超时控制**## HTTP客户端标准实现### 客户端定义规范```go// 客户端标准定义type XXXHttpClient struct {    // 可选的客户端配置}// 必须定义统一的初始化方法func NewXXXHttpClient(ctx context.Context) *XXXHttpClient {    return &XXXHttpClient{}}```### 请求参数定义```go// 请求参数必须使用结构体定义type RequestParams struct {    // 请求字段    Field1 string `json:"field1"`    Field2 int    `json:"field2"`    // ...}```### 标准HTTP调用实现```go// 标准HTTP调用方法func (client *XXXHttpClient) SendRequest(ctx context.Context, params RequestParams) (ResponseType, error) {    // 1. 从配置中心获取URL配置    var conf simplehttp.URLSetting    urlConf := mconfig.UrlConfig()    if err := urlConf.UnmarshalKey("ConfigKey", &conf); err != nil || conf.URL == "" {        return nil, common.Errorf(common.ErrorInternal, "url conf miss")    }    // 2. 构建URL和请求参数    url := conf.URL + "/api/endpoint"    httpParams := map[string]string{        "param1": params.Field1,        "param2": types.IWrapper(params.Field2).String(),        // 必须加入追踪ID        "trace_id": eagleeye.GetTraceId(ctx),    }    // 3. 构建请求选项    opt := simplehttp.BuildOptions(&simplehttp.Options{        Method:           "GET", // 或 POST 等        Params:           httpParams,        Timeout:          conf.Timeout,        HostWithVip:      conf.VipHost,        RecordWithParams: httpcommon.RecordWithParams,    })    // 4. 发送请求并记录日志    respData, err := simplehttp.RequestWithContext(ctx, url, opt)    common.LogInfof(ctx, "log_type", "request info, params=%v, err=%v", params, err)    // 5. 错误处理    if err != nil {        return nil, common.Errorf(common.ErrorInternal, "request failed.err:%s", err.Error())    }    // 6. 解析响应    var response ResponseType    err = json.Unmarshal(respData, &response)    if err != nil {        return nil, common.Errorf(common.ErrorInternal, "unmarshal failed.err:%s", err.Error())    }    // 7. 返回结果    return response, nil}```### 带缓存的HTTP调用```gofunc GetDataWithCache(ctx context.Context, key string, params RequestParams) (ResponseType, error) {    var resp ResponseType    cacheKey := fmt.Sprintf("cache_key_prefix_%s", key)    // 使用缓存机制    err := mcache.GetLocalCacheFiveSecond(ctx).Once(ctx, cacheKey, &resp, 5*time.Second, func() (interface{}, error) {        // 调用实际API        data, e := SendRequest(ctx, params)        // 记录日志        common.LogDebugf(ctx, "module_name", "GetData, key:%s, data:%+v, err:%v", key, data, e)        // 错误处理        if e != nil {            return nil, errors.New(e.Error())        }        return data, nil    })    if err != nil {        return nil, err    }    return resp, nil}```## HSF客户端标准实现### 服务定义规范```go// 全局服务实例var XXXService = new(XXXServiceImpl)// 注册HSF模型func init() {    hsfCommon.RegisterModel(&ModelType1{})    hsfCommon.RegisterModel(&ModelType2{})    // 其他模型注册...}// 服务结构体定义type XXXServiceImpl struct {    // 方法定义，必须遵循标准方法签名    MethodName func(ctx context.Context, args []interface{}) (*ResponseType, error)}// 接口名配置func (s *XXXServiceImpl) InterfaceName() string {    return mconfig.UrlConfig().GetString("ServiceName.interfaceName")}// 版本配置func (s *XXXServiceImpl) Version() string {    return mconfig.UrlConfig().GetString("ServiceName.version")}// 组名配置func (s *XXXServiceImpl) Group() string {    return mconfig.UrlConfig().GetString("ServiceName.group")}// 超时配置func (s *XXXServiceImpl) TimeoutMs() int {    return mconfig.UrlConfig().GetInt("ServiceName.timeout")}```### 请求模型定义```go// 请求模型必须实现JavaClassName方法type RequestType struct {    Field1 string    `json:"field1" hessian:"field1"`    Field2 int64     `json:"field2" hessian:"field2"`    // ...}func (RequestType) JavaClassName() string {    return"com.package.RequestType"}// 响应模型必须实现JavaClassName方法type ResponseType struct {    Code    int32       `json:"code"`    Data    interface{} `json:"data"`    Success bool        `json:"success"`    // ...}func (ResponseType) JavaClassName() string {    return"com.package.ResponseType"}```### 标准HSF调用实现```go// 标准HSF调用方法func CallHSFService(ctx context.Context, request *RequestType) (*DataType, *common.Error) {    // 1. 调用HSF服务    hsfResp, e := XXXService.MethodName(ctx, []interface{}{request})    // 2. 记录请求和响应日志    reqJson, _ := json.Marshal(request)    respJson, _ := json.Marshal(hsfResp)    common.LogInfof(ctx, "hsf_call", "hsf resp:%s, err:%v, req:%s",        string(respJson), e, string(reqJson))    // 3. 错误处理    if e != nil {        return nil, common.Errorf(common.ErrorInternal, "HSF call failed.err:%s", e.Error())    }    // 4. 结果处理    if hsfResp != nil {        result := ParseResponseData(hsfResp.Data)        return result, nil    }    return nil, nil}// 解析响应数据的标准方法func ParseResponseData(data interface{}) *DataType {    if data == nil {        return nil    }    if items, ok := data.(SpecificResponseType); ok {        // 处理数据转换        result := &DataType{            // 数据转换逻辑        }        return result    }    return nil}```### 带缓存的HSF调用```gofunc GetHSFDataWithCache(ctx context.Context, param1, param2 string) (*DataType, error) {    var resp *DataType    cacheKey := fmt.Sprintf("hsf_cache_key_%s_%s", param1, param2)    // 使用缓存机制    err := mcache.GetLocalCacheFiveSecond(ctx).Once(ctx, cacheKey, &resp, 5*time.Second, func() (interface{}, error) {        // 构建HSF请求        request := &RequestType{            Field1: param1,            Field2: param2,        }        // 调用HSF服务        data, e := CallHSFService(ctx, request)        // 记录日志        common.LogDebugf(ctx, "hsf_module", "GetHSFData, key:%s, data:%+v, err:%v", cacheKey, data, e)        // 错误处理        if e != nil {            return nil, errors.New(e.Error())        }        return data, nil    })    if err != nil {        return nil, err    }    return resp, nil}```## 错误处理规范- **所有中间件调用都必须返回标准化的错误**- **错误必须包含错误码和错误信息**- **网络错误必须归类为InternalError**- **参数错误必须归类为InvalidError**- **业务逻辑错误必须根据具体场景进行分类**```go// 错误处理示例if err != nil {    // 网络错误    if netErr, ok := err.(net.Error); ok && netErr.Timeout() {        return nil, common.Errorf(common.ErrorTimeout, "request timeout: %s", err.Error())    }    // 一般错误    return nil, common.Errorf(common.ErrorInternal, "request failed: %s", err.Error())}// 业务错误if resp.Code != 200 {    return nil, common.Errorf(common.ErrorBusiness, "business error: %s", resp.Message)}```## 日志记录规范- **所有中间件调用必须记录请求和响应日志**- **日志必须包含追踪ID、请求参数和响应结果**- **敏感信息（如密码、token）必须在日志中脱敏**- **必须使用统一的日志模块和日志格式**```go// 标准日志示例common.LogInfof(ctx, "module_name", "method_name, param1=%v, param2=%v, resp=%s, err=%v",    param1, param2, respJson, err)```## 示例<example>// HTTP客户端调用示例package clientimport (    "amap-aos-activity/basic/common"    "amap-aos-activity/framework/mconfig"    "context"    "encoding/json"    "fmt"    "gitlab.alibaba-inc.com/amap-go/eagleeye-go"    "gitlab.alibaba-inc.com/amap-go/http-client/simplehttp"    httpcommon "gitlab.alibaba-inc.com/amap-go/http-client/common"    "time")// 请求参数定义type SearchParams struct {    Query    string  `json:"query"`    Latitude float64 `json:"latitude"`    Longitude float64 `json:"longitude"`}// 响应结构定义type SearchResponse struct {    Code    int           `json:"code"`    Message string        `json:"message"`    Data    []SearchItem  `json:"data"`}type SearchItem struct {    ID      string  `json:"id"`    Name    string  `json:"name"`    Distance float64 `json:"distance"`}// 发送搜索请求func SendSearchRequest(ctx context.Context, params SearchParams) (*SearchResponse, *common.Error) {    // 从配置中获取URL    var conf simplehttp.URLSetting    urlConf := mconfig.UrlConfig()    if err := urlConf.UnmarshalKey("SearchService", &conf); err != nil || conf.URL == "" {        return nil, common.Errorf(common.ErrorInternal, "search service url conf miss")    }    // 构建请求参数    httpParams := map[string]string{        "query": params.Query,        "latitude": fmt.Sprintf("%f", params.Latitude),        "longitude": fmt.Sprintf("%f", params.Longitude),        "trace_id": eagleeye.GetTraceId(ctx),    }    // 构建请求选项    opt := simplehttp.BuildOptions(&simplehttp.Options{        Method:           "GET",        Params:           httpParams,        Timeout:          conf.Timeout,        HostWithVip:      conf.VipHost,        RecordWithParams: httpcommon.RecordWithParams,    })    // 发送请求    url := conf.URL + "/search/api"    respData, err := simplehttp.RequestWithContext(ctx, url, opt)    common.LogInfof(ctx, "search_service", "search request, params=%v, err=%v", params, err)    // 错误处理    if err != nil {        return nil, common.Errorf(common.ErrorInternal, "search request failed: %s", err.Error())    }    // 解析响应    var response SearchResponse    if err := json.Unmarshal(respData, &response); err != nil {        return nil, common.Errorf(common.ErrorInternal, "unmarshal search response failed: %s", err.Error())    }    // 业务错误处理    if response.Code != 200 {        return nil, common.Errorf(common.ErrorBusiness, "search business error: %s", response.Message)    }    return &response, nil}// 带缓存的搜索请求func SearchWithCache(ctx context.Context, params SearchParams) (*SearchResponse, error) {    var resp *SearchResponse    cacheKey := fmt.Sprintf("search_%s_%f_%f", params.Query, params.Latitude, params.Longitude)    err := mcache.GetLocalCacheFiveSecond(ctx).Once(ctx, cacheKey, &resp, 30*time.Second, func() (interface{}, error) {        result, e := SendSearchRequest(ctx, params)        if e != nil {            return nil, e        }        return result, nil    })    if err != nil {        return nil, err    }    return resp, nil}</example><example>// HSF客户端调用示例package clientimport (    "amap-aos-activity/basic/common"    "amap-aos-activity/framework/mconfig"    "context"    "encoding/json"    "errors"    "fmt"    hsfCommon "gitlab.alibaba-inc.com/amap-go/hsf-go/common"    "time")// 全局服务实例var ProductService = new(ProductServiceImpl)// 注册HSF模型func init() {    hsfCommon.RegisterModel(&ProductQueryRequest{})    hsfCommon.RegisterModel(&ProductQueryResponse{})    hsfCommon.RegisterModel(&ProductDetail{})}// 请求模型type ProductQueryRequest struct {    ProductId string   `json:"productId" hessian:"productId"`    Fields    []string `json:"fields" hessian:"fields"`}func (ProductQueryRequest) JavaClassName() string {    return"com.example.product.request.ProductQueryRequest"}// 响应模型type ProductQueryResponse struct {    Code    int32         `json:"code"`    Data    *ProductDetail `json:"data"`    Success bool          `json:"success"`    Message string        `json:"message"`}func (ProductQueryResponse) JavaClassName() string {    return"com.example.product.response.ProductQueryResponse"}// 产品详情type ProductDetail struct {    Id          string  `json:"id" hessian:"id"`    Name        string  `json:"name" hessian:"name"`    Price       int64   `json:"price" hessian:"price"`    Description string  `json:"description" hessian:"description"`}func (ProductDetail) JavaClassName() string {    return"com.example.product.model.ProductDetail"}// 服务结构体type ProductServiceImpl struct {    QueryProduct func(ctx context.Context, args []interface{}) (*ProductQueryResponse, error)}// 接口配置func (s *ProductServiceImpl) InterfaceName() string {    return mconfig.UrlConfig().GetString("ProductService.interfaceName")}func (s *ProductServiceImpl) Version() string {    return mconfig.UrlConfig().GetString("ProductService.version")}func (s *ProductServiceImpl) Group() string {    return mconfig.UrlConfig().GetString("ProductService.group")}func (s *ProductServiceImpl) TimeoutMs() int {    return mconfig.UrlConfig().GetInt("ProductService.timeout")}// 查询产品信息func GetProductDetail(ctx context.Context, productId string) (*ProductDetail, *common.Error) {    // 构建请求    request := &ProductQueryRequest{        ProductId: productId,        Fields: []string{"id", "name", "price", "description"},    }    // 调用HSF服务    resp, err := ProductService.QueryProduct(ctx, []interface{}{request})    // 记录日志    reqJson, _ := json.Marshal(request)    respJson, _ := json.Marshal(resp)    common.LogInfof(ctx, "product_service", "query product, req=%s, resp=%s, err=%v",        string(reqJson), string(respJson), err)    // 错误处理    if err != nil {        return nil, common.Errorf(common.ErrorInternal, "query product failed: %s", err.Error())    }    // 结果处理    if resp != nil {        if !resp.Success || resp.Code != 200 {            return nil, common.Errorf(common.ErrorBusiness, "business error: %s", resp.Message)        }        return resp.Data, nil    }    return nil, common.Errorf(common.ErrorInternal, "empty response")}// 带缓存的产品查询func GetProductWithCache(ctx context.Context, productId string) (*ProductDetail, error) {    var product *ProductDetail    cacheKey := fmt.Sprintf("product_detail_%s", productId)    err := mcache.GetLocalCacheFiveSecond(ctx).Once(ctx, cacheKey, &product, 5*time.Minute, func() (interface{}, error) {        detail, e := GetProductDetail(ctx, productId)        if e != nil {            return nil, errors.New(e.Error())        }        return detail, nil    })    if err != nil {        return nil, err    }    return product, nil}</example><example type="invalid">// 错误示例：硬编码URL和缺少日志记录package clientimport (    "context"    "encoding/json"    "net/http"    "io/ioutil")// 错误1: 硬编码URL// 错误2: 没有使用配置中心// 错误3: 没有传递和使用contextfunc BadSearchRequest(query string) ([]byte, error) {    // 硬编码URL    url := "http://search.example.com/api?query=" + query    // 没有超时控制    resp, err := http.Get(url)    if err != nil {        return nil, err    }    defer resp.Body.Close()    // 没有日志记录    return ioutil.ReadAll(resp.Body)}// 错误示例：HSF调用不规范var badHsfService = struct {    Method func(args []interface{}) (interface{}, error)}{}// 错误1: 不遵循标准接口定义// 错误2: 没有使用Context参数// 错误3: 没有注册模型// 错误4: 错误处理不规范func BadHsfCall(id string) interface{} {    result, _ := badHsfService.Method([]interface{}{id})    // 忽略错误处理    return result}</example>

SYSTEM_PROMPT = """你是Auto-GPT，一个自主的AI助手。你的目标是：{ai_goals}你的角色是：{ai_role}
约束条件：1. 只能使用提供的命令和工具2. 每次只执行一个命令3. 必须基于当前情况做出最佳决策4. 保持专注于目标5. 避免无限循环
可用命令：{commands}
资源限制：- 令牌预算：{token_budget}- 最大步数：{max_steps}"""

THINKING_PROMPT = """当前情况分析：1. 我已经完成了什么？2. 下一步需要做什么？3. 哪个命令最适合当前情况？4. 执行后的预期结果是什么？
决策理由：基于以上分析，我选择执行：{chosen_command}"""

RESEARCH_PROMPT = """作为研究分析师，请：1. 收集相关信息：{topic}2. 验证信息的可靠性3. 分析关键要点4. 总结发现和结论5. 提供可行的建议
研究方法：- 使用多个可靠来源- 交叉验证信息- 保持客观中立- 区分事实和观点"""

WEB_SEARCH_PROMPT = """进行网络搜索时：1. 使用精确的搜索关键词2. 评估搜索结果的相关性3. 筛选可靠的信息源4. 提取关键信息5. 避免过时或不准确的信息
搜索策略：- 组合多个关键词- 使用引号精确匹配- 筛选时间范围- 验证信息来源"""

REFLECTION_PROMPT = """执行完成后的自我评估：
执行结果：✅ 成功完成的任务：{completed_tasks}❌ 遇到的问题：{encountered_issues}🔄 需要重试的操作：{retry_needed}
学习总结：1. 这次执行中学到了什么？2. 哪些策略是有效的？3. 下次可以如何改进？4. 是否需要调整方法？
下一步计划：基于当前进展，下一步应该：{next_action}"""

ERROR_HANDLING_PROMPT = """遇到错误时的处理策略：
错误分析：- 错误类型：{error_type}- 错误原因：{error_cause}- 影响范围：{impact_scope}
解决方案：1. 立即处理方案：{immediate_solution}2. 替代方案：{alternative_approaches}3. 预防措施：{prevention_measures}
学习记录：将此错误及解决方法记录，避免重复发生"""

CONTEXT_MANAGEMENT = """上下文信息管理：- 短期记忆：最近3-5步的执行历史- 长期目标：始终保持对主要目标的关注- 环境状态：当前工作目录、可用资源等- 约束条件：时间、预算、权限限制"""