e1f83ae469
## 主要改进 ### 架构重构 - 将单体 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.
121 lines
5.4 KiB
Markdown
121 lines
5.4 KiB
Markdown
# 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
|
||
|
||
--- |