feat: 重构 pkg/ast/provider 模块，优化代码组织逻辑和功能实现
## 主要改进 ### 架构重构 - 将单体 provider.go 拆分为多个专门的模块文件 - 实现了清晰的职责分离和模块化设计 - 遵循 SOLID 原则，提高代码可维护性 ### 新增功能 - **验证规则系统**: 实现了完整的 provider 验证框架 - **报告生成器**: 支持多种格式的验证报告 (JSON/HTML/Markdown/Text) - **解析器优化**: 重新设计了解析流程，提高性能和可扩展性 - **错误处理**: 增强了错误处理和诊断能力 ### 修复关键 Bug - 修复 @provider(job) 注解缺失 __job 注入参数的问题 - 统一了 job 和 cronjob 模式的处理逻辑 - 确保了 provider 生成的正确性和一致性 ### 代码质量提升 - 添加了完整的测试套件 - 引入了 golangci-lint 代码质量检查 - 优化了代码格式和结构 - 增加了详细的文档和规范 ### 文件结构优化 ``` pkg/ast/provider/ ├── types.go # 类型定义 ├── parser.go # 解析器实现 ├── validator.go # 验证规则 ├── report_generator.go # 报告生成 ├── renderer.go # 渲染器 ├── comment_parser.go # 注解解析 ├── modes.go # 模式定义 ├── errors.go # 错误处理 └── validator_test.go # 测试文件 ``` ### 兼容性 - 保持向后兼容性 - 支持现有的所有 provider 模式 - 优化了 API 设计和用户体验 This completes the implementation of T025-T029 tasks following TDD principles, including validation rules implementation and critical bug fixes.
This commit is contained in:
Rogee
121
specs/001-pkg-ast-provider/spec.md
Normal file
121
specs/001-pkg-ast-provider/spec.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# Feature Specification: 优化 pkg/ast/provider 目录的代码组织逻辑与功能实现
|
||||
|
||||
**Feature Branch**: `001-pkg-ast-provider`
|
||||
**Created**: 2025-09-19
|
||||
**Status**: Draft
|
||||
**Input**: User description: "优化 @pkg/ast/provider/ 目录的代码组织逻辑与功能实现，补充完善测试用例"
|
||||
|
||||
## Execution Flow (main)
|
||||
```
|
||||
1. Parse user description from Input
|
||||
→ If empty: ERROR "No feature description provided"
|
||||
2. Extract key concepts from description
|
||||
→ Identify: actors, actions, data, constraints
|
||||
3. For each unclear aspect:
|
||||
→ Mark with [NEEDS CLARIFICATION: specific question]
|
||||
4. Fill User Scenarios & Testing section
|
||||
→ If no clear user flow: ERROR "Cannot determine user scenarios"
|
||||
5. Generate Functional Requirements
|
||||
→ Each requirement must be testable
|
||||
→ Mark ambiguous requirements
|
||||
6. Identify Key Entities (if data involved)
|
||||
7. Run Review Checklist
|
||||
→ If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
|
||||
→ If implementation details found: ERROR "Remove tech details"
|
||||
8. Return: SUCCESS (spec ready for planning)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Quick Guidelines
|
||||
- ✅ Focus on WHAT users need and WHY
|
||||
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
|
||||
- 👥 Written for business stakeholders, not developers
|
||||
|
||||
### Section Requirements
|
||||
- **Mandatory sections**: Must be completed for every feature
|
||||
- **Optional sections**: Include only when relevant to the feature
|
||||
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
|
||||
|
||||
### For AI Generation
|
||||
When creating this spec from a user prompt:
|
||||
1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
|
||||
2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
|
||||
3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
|
||||
4. **Common underspecified areas**:
|
||||
- User types and permissions
|
||||
- Data retention/deletion policies
|
||||
- Performance targets and scale
|
||||
- Error handling behaviors
|
||||
- Integration requirements
|
||||
- Security/compliance needs
|
||||
|
||||
---
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
|
||||
### Primary User Story
|
||||
作为开发者，我需要使用 atomctl 工具来解析 Go 源码中的 `@provider` 注释，并生成相应的依赖注入代码。我希望代码组织逻辑清晰，功能实现可靠，并且有完整的测试用例来保证代码质量。
|
||||
|
||||
### Acceptance Scenarios
|
||||
1. **Given** 一个包含 `@provider` 注释的 Go 源码文件，**When** 我运行解析功能，**Then** 系统能正确提取所有 provider 信息并生成相应的代码
|
||||
2. **Given** 一个复杂的 Go 项目结构，**When** 我解析多个文件中的 provider，**Then** 系统能正确处理跨文件的依赖关系
|
||||
3. **Given** 一个包含错误注释格式的源码文件，**When** 我运行解析功能，**Then** 系统能提供清晰的错误信息和建议
|
||||
4. **Given** 生成的 provider 代码，**When** 我运行测试套件，**Then** 所有测试都能通过，覆盖率达到 90%
|
||||
|
||||
### Edge Cases
|
||||
- 当源码文件格式不正确时，系统如何处理？
|
||||
- 当注释格式不规范时，系统如何提供有用的错误信息？
|
||||
- 当处理大型项目时，系统性能如何保证？
|
||||
- 当并发处理多个文件时，如何保证线程安全？
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
### Functional Requirements
|
||||
- **FR-001**: System MUST 能够解析 `@provider` 注释的各种格式（基本格式、带模式、带返回类型、带分组等）
|
||||
- **FR-002**: System MUST 支持不同的 provider 模式（grpc、event、job、cronjob、model）
|
||||
- **FR-003**: System MUST 正确处理依赖注入参数（only/except 模式、包名解析、类型识别）
|
||||
- **FR-004**: System MUST 能够生成结构化的 provider 代码，包括必要的导入和函数定义
|
||||
- **FR-005**: System MUST 提供完整的错误处理机制，包括语法错误、导入错误等
|
||||
- **FR-006**: System MUST 包含全面的测试用例，覆盖所有主要功能和边界情况
|
||||
- **FR-007**: System MUST 优化代码组织结构，提高代码的可读性和可维护性
|
||||
- **FR-008**: System MUST 处理复杂的包导入和别名解析逻辑
|
||||
|
||||
### Key Entities *(include if feature involves data)*
|
||||
- **Provider**: 代表一个依赖注入提供者的核心实体，包含结构名、返回类型、模式等属性
|
||||
- **ProviderDescribe**: 描述 provider 注释解析结果的实体，包含模式、返回类型、分组等信息
|
||||
- **InjectParam**: 描述注入参数的实体，包含类型、包名、别名等信息
|
||||
- **SourceFile**: 代表待解析的源码文件，包含文件路径、内容、导入信息等
|
||||
|
||||
---
|
||||
|
||||
## Review & Acceptance Checklist
|
||||
*GATE: Automated checks run during main() execution*
|
||||
|
||||
### Content Quality
|
||||
- [ ] No implementation details (languages, frameworks, APIs)
|
||||
- [ ] Focused on user value and business needs
|
||||
- [ ] Written for non-technical stakeholders
|
||||
- [ ] All mandatory sections completed
|
||||
|
||||
### Requirement Completeness
|
||||
- [ ] No [NEEDS CLARIFICATION] markers remain
|
||||
- [ ] Requirements are testable and unambiguous
|
||||
- [ ] Success criteria are measurable
|
||||
- [ ] Scope is clearly bounded
|
||||
- [ ] Dependencies and assumptions identified
|
||||
|
||||
---
|
||||
|
||||
## Execution Status
|
||||
*Updated by main() during processing*
|
||||
|
||||
- [ ] User description parsed
|
||||
- [ ] Key concepts extracted
|
||||
- [ ] Ambiguities marked
|
||||
- [ ] User scenarios defined
|
||||
- [ ] Requirements generated
|
||||
- [ ] Entities identified
|
||||
- [ ] Review checklist passed
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user