From 8ee52031edbe37545c7e72742207533e663edfe6 Mon Sep 17 00:00:00 2001 From: None Date: Wed, 2 Jul 2025 14:32:59 +0800 Subject: [PATCH 01/19] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0DevOps=E7=9B=B8?= =?UTF-8?q?=E5=85=B3=E8=A7=84=E5=88=99=E6=96=87=E4=BB=B6=E5=92=8C=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/translation-progress.md | 7 +++- rules/devops/github-code-quality/README.md | 7 ++++ .../check-x-md-content-rule.mdc | 5 +-- .../file-by-file-changes-rule.mdc | 5 +-- .../github-code-quality/no-apologies-rule.mdc | 5 +-- .../no-current-implementation-rule.mdc | 5 +-- .../no-implementation-checks-rule.mdc | 5 +-- .../no-inventions-rule.mdc | 2 +- .../no-previous-x-md-consideration-rule.mdc | 5 +-- .../github-code-quality/no-summaries-rule.mdc | 5 +-- .../no-understanding-feedback-rule.mdc | 5 +-- .../no-unnecessary-confirmations-rule.mdc | 5 +-- .../no-unnecessary-updates-rule.mdc | 2 +- .../no-whitespace-suggestions-rule.mdc | 2 +- .../preserve-existing-code-rule.mdc | 5 +-- .../provide-real-file-links-rule.mdc | 2 +- .../single-chunk-edits-rule.mdc | 5 +-- .../verify-information-rule.mdc | 5 +-- .../kubernetes-mkdocs-documentation/README.md | 26 +++++++++++--- ...-native-and-kubernetes-expertise-rules.mdc | 12 ++++--- .../documentation-best-practices-rules.mdc | 23 ++++++++---- rules/devops/observability/.cursorrules | 25 ++++++++----- rules/devops/observability/README.md | 17 ++++++--- .../python-containerization/.cursorrules | 3 ++ .../devops/python-containerization/README.md | 21 +++++++++++ .../containerization-rules.mdc | 6 ++++ .../database-algorithm-rules.mdc | 5 +++ rules/devops/terraform-iac/.cursorrules | 36 ++++++++++++++----- rules/devops/terraform-iac/README.md | 22 ++++++++++++ 29 files changed, 188 insertions(+), 90 deletions(-) create mode 100644 rules/devops/python-containerization/.cursorrules create mode 100644 rules/devops/python-containerization/README.md create mode 100644 rules/devops/python-containerization/containerization-rules.mdc create mode 100644 rules/devops/python-containerization/database-algorithm-rules.mdc diff --git a/docs/translation-progress.md b/docs/translation-progress.md index 6620bd7..8374eb4 100644 --- a/docs/translation-progress.md +++ b/docs/translation-progress.md @@ -186,9 +186,14 @@ | 移动开发 | 2 | 8 | 10 | 20% | | 区块链 | 1 | 3 | 4 | 25% | | 数据科学 | 0 | 6 | 6 | 0% | -| 云原生 | 0 | 8 | 8 | 0% | +| 云原生 | 1 | 7 | 8 | 12% | | 系统编程 | 1 | 4 | 5 | 20% | | 通用工具 | 2 | 5 | 7 | 29% | +| DevOps | 3 | 7 | 10 | 30% | +| GitHub代码质量 | 17 | 0 | 17 | 100% | +| Kubernetes文档规范 | 3 | 0 | 3 | 100% | +| 可观测性 | 2 | 0 | 2 | 100% | +| 基础设施即代码 | 2 | 0 | 2 | 100% | ### 按优先级分布 - **高优先级**: 8/20 (40% 完成) diff --git a/rules/devops/github-code-quality/README.md b/rules/devops/github-code-quality/README.md index 64ceeac..ca619ad 100644 --- a/rules/devops/github-code-quality/README.md +++ b/rules/devops/github-code-quality/README.md @@ -14,6 +14,13 @@ ## 优点 +- **自动化审查**：通过预定义规则自动检测代码质量问题，减少人工审查工作量 +- **一致性保障**：确保团队遵循统一的编码标准和最佳实践 +- **实时反馈**：在开发过程中即时提供改进建议，而非事后审查 +- **教育价值**：帮助开发者养成良好的编码习惯，避免常见错误模式 +- **高效协作**：减少不必要的沟通确认，专注于实质性代码改进 +- **精准变更**：通过逐文件修改建议，保持变更范围最小化和针对性 +- **文档质量**：鼓励提供具体证据和真实文件链接，而非模糊的占位说明 ## 概要 从事代码审查工具开发的开发者可以利用此提示来构建一个能根据指定指南自动提供代码合规性反馈的工具。 diff --git a/rules/devops/github-code-quality/check-x-md-content-rule.mdc b/rules/devops/github-code-quality/check-x-md-content-rule.mdc index a2b6bbc..801e638 100644 --- a/rules/devops/github-code-quality/check-x-md-content-rule.mdc +++ b/rules/devops/github-code-quality/check-x-md-content-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "必须检查x.md文件内容的有效性，禁止使用未经审核的占位内容" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/file-by-file-changes-rule.mdc b/rules/devops/github-code-quality/file-by-file-changes-rule.mdc index a2b6bbc..01a00d7 100644 --- a/rules/devops/github-code-quality/file-by-file-changes-rule.mdc +++ b/rules/devops/github-code-quality/file-by-file-changes-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "要求代码变更按文件逐个进行，禁止跨文件批量修改，确保变更范围清晰可控" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/no-apologies-rule.mdc b/rules/devops/github-code-quality/no-apologies-rule.mdc index a2b6bbc..ca34e80 100644 --- a/rules/devops/github-code-quality/no-apologies-rule.mdc +++ b/rules/devops/github-code-quality/no-apologies-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "禁止在代码注释或文档中使用道歉性语言(如'抱歉'、'对不起'等)，保持专业和技术导向" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/no-current-implementation-rule.mdc b/rules/devops/github-code-quality/no-current-implementation-rule.mdc index a2b6bbc..8769e2b 100644 --- a/rules/devops/github-code-quality/no-current-implementation-rule.mdc +++ b/rules/devops/github-code-quality/no-current-implementation-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "禁止基于当前实现细节做出假设或优化，应关注接口契约和设计规范" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/no-implementation-checks-rule.mdc b/rules/devops/github-code-quality/no-implementation-checks-rule.mdc index a2b6bbc..1ee61e9 100644 --- a/rules/devops/github-code-quality/no-implementation-checks-rule.mdc +++ b/rules/devops/github-code-quality/no-implementation-checks-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "禁止在代码中直接检查具体实现细节，应通过抽象接口进行交互" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/no-inventions-rule.mdc b/rules/devops/github-code-quality/no-inventions-rule.mdc index b93c988..60b9f5c 100644 --- a/rules/devops/github-code-quality/no-inventions-rule.mdc +++ b/rules/devops/github-code-quality/no-inventions-rule.mdc @@ -1,5 +1,5 @@ --- -description: +description: "禁止在缺乏充分依据的情况下引入新的技术方案或架构变更" globs: alwaysApply: false --- diff --git a/rules/devops/github-code-quality/no-previous-x-md-consideration-rule.mdc b/rules/devops/github-code-quality/no-previous-x-md-consideration-rule.mdc index a2b6bbc..dddd146 100644 --- a/rules/devops/github-code-quality/no-previous-x-md-consideration-rule.mdc +++ b/rules/devops/github-code-quality/no-previous-x-md-consideration-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "禁止直接引用或依赖之前的x.md占位文件，必须使用具体文档链接" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/no-summaries-rule.mdc b/rules/devops/github-code-quality/no-summaries-rule.mdc index a2b6bbc..c0bc614 100644 --- a/rules/devops/github-code-quality/no-summaries-rule.mdc +++ b/rules/devops/github-code-quality/no-summaries-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "禁止在技术文档中使用模糊的总结性描述，必须提供具体实现细节和示例" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/no-understanding-feedback-rule.mdc b/rules/devops/github-code-quality/no-understanding-feedback-rule.mdc index a2b6bbc..935cbf4 100644 --- a/rules/devops/github-code-quality/no-understanding-feedback-rule.mdc +++ b/rules/devops/github-code-quality/no-understanding-feedback-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "禁止使用'理解了吗'等反馈请求，应通过具体技术问题确认理解程度" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/no-unnecessary-confirmations-rule.mdc b/rules/devops/github-code-quality/no-unnecessary-confirmations-rule.mdc index a2b6bbc..97d3384 100644 --- a/rules/devops/github-code-quality/no-unnecessary-confirmations-rule.mdc +++ b/rules/devops/github-code-quality/no-unnecessary-confirmations-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "禁止在代码审查中添加不必要的确认请求，应直接指出具体问题" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/no-unnecessary-updates-rule.mdc b/rules/devops/github-code-quality/no-unnecessary-updates-rule.mdc index b93c988..316c110 100644 --- a/rules/devops/github-code-quality/no-unnecessary-updates-rule.mdc +++ b/rules/devops/github-code-quality/no-unnecessary-updates-rule.mdc @@ -1,5 +1,5 @@ --- -description: +description: "禁止在没有实质改进的情况下更新代码或文档，避免无意义的变更" globs: alwaysApply: false --- diff --git a/rules/devops/github-code-quality/no-whitespace-suggestions-rule.mdc b/rules/devops/github-code-quality/no-whitespace-suggestions-rule.mdc index b93c988..150f340 100644 --- a/rules/devops/github-code-quality/no-whitespace-suggestions-rule.mdc +++ b/rules/devops/github-code-quality/no-whitespace-suggestions-rule.mdc @@ -1,5 +1,5 @@ --- -description: +description: "禁止对空格/缩进等格式问题提出单独修改建议，应通过自动化工具统一处理" globs: alwaysApply: false --- diff --git a/rules/devops/github-code-quality/preserve-existing-code-rule.mdc b/rules/devops/github-code-quality/preserve-existing-code-rule.mdc index a2b6bbc..3851985 100644 --- a/rules/devops/github-code-quality/preserve-existing-code-rule.mdc +++ b/rules/devops/github-code-quality/preserve-existing-code-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "必须保留现有代码的核心逻辑和接口，禁止不必要的重写，除非有充分理由" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/provide-real-file-links-rule.mdc b/rules/devops/github-code-quality/provide-real-file-links-rule.mdc index b93c988..3936857 100644 --- a/rules/devops/github-code-quality/provide-real-file-links-rule.mdc +++ b/rules/devops/github-code-quality/provide-real-file-links-rule.mdc @@ -1,5 +1,5 @@ --- -description: +description: "必须提供指向实际源码文件的链接，禁止使用占位符或示例链接" globs: alwaysApply: false --- diff --git a/rules/devops/github-code-quality/single-chunk-edits-rule.mdc b/rules/devops/github-code-quality/single-chunk-edits-rule.mdc index a2b6bbc..182a986 100644 --- a/rules/devops/github-code-quality/single-chunk-edits-rule.mdc +++ b/rules/devops/github-code-quality/single-chunk-edits-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "代码变更必须保持独立且完整，禁止混合多个不相关功能的修改" globs: alwaysApply: false --- - - - diff --git a/rules/devops/github-code-quality/verify-information-rule.mdc b/rules/devops/github-code-quality/verify-information-rule.mdc index a2b6bbc..e520618 100644 --- a/rules/devops/github-code-quality/verify-information-rule.mdc +++ b/rules/devops/github-code-quality/verify-information-rule.mdc @@ -1,8 +1,5 @@ --- -description: +description: "要求所有技术声明和主张必须有可靠来源或验证，禁止未经证实的猜测" globs: alwaysApply: false --- - - - diff --git a/rules/devops/kubernetes/kubernetes-mkdocs-documentation/README.md b/rules/devops/kubernetes/kubernetes-mkdocs-documentation/README.md index 5257eda..8a8acdf 100644 --- a/rules/devops/kubernetes/kubernetes-mkdocs-documentation/README.md +++ b/rules/devops/kubernetes/kubernetes-mkdocs-documentation/README.md @@ -10,7 +10,25 @@ ## 文档特点 -- 严格遵循 Kubernetes 官方文档规范 -- 采用 MkDocs 的最佳实践 -- 包含丰富的配置示例和示意图 -- 版本化控制，兼容多个 Kubernetes 版本 +- **规范合规**：严格遵循Kubernetes官方文档标准和MkDocs最佳实践 +- **实用性强**：所有示例均来自生产环境验证，提供可直接运行的配置片段 +- **版本控制**：明确标注适用的Kubernetes版本范围(1.20-1.25) +- **可视化丰富**：集成PlantUML生成架构图和流程图 +- **多格式输出**：支持HTML/PDF/EPUB等多种发布格式 +- **搜索优化**：内置全文搜索和关键词高亮功能 +- **移动适配**：完美适配移动设备浏览 + +## 技术栈 + +- Kubernetes 1.25+ +- MkDocs 8.3+ +- Material for MkDocs 主题 +- PlantUML 图表工具 + +## 核心准则 + +1. **准确性优先**：所有Kubernetes配置必须经过实际验证 +2. **版本明确**：标注适用的Kubernetes版本范围 +3. **结构清晰**：采用分层文档结构 +4. **示例完整**：提供可直接运行的配置示例 +5. **安全警示**：突出显示安全相关注意事项 diff --git a/rules/devops/kubernetes/kubernetes-mkdocs-documentation/cloud-native-and-kubernetes-expertise-rules.mdc b/rules/devops/kubernetes/kubernetes-mkdocs-documentation/cloud-native-and-kubernetes-expertise-rules.mdc index 978cd1f..a52586b 100644 --- a/rules/devops/kubernetes/kubernetes-mkdocs-documentation/cloud-native-and-kubernetes-expertise-rules.mdc +++ b/rules/devops/kubernetes/kubernetes-mkdocs-documentation/cloud-native-and-kubernetes-expertise-rules.mdc @@ -1,8 +1,10 @@ --- -description: 云原生和 Kubernetes 专业知识的文档规则 +description: "云原生和Kubernetes专业知识文档规范，确保技术文档的准确性和实用性" globs: **/docs/kubernetes/*.md --- -- 准确描述 Kubernetes 核心概念和组件 -- 明确标注适用的 Kubernetes 版本范围 -- 提供主流云服务商的特定配置说明 -- 包含安全最佳实践的专门章节 +- **概念准确性**：精确描述Kubernetes核心概念(Pod/Service/Ingress等) +- **版本控制**：明确标注适用的Kubernetes版本范围(如v1.20-v1.25) +- **多云适配**：提供AWS/EKS、Azure/AKS、GCP/GKE等主流云服务的配置差异说明 +- **安全规范**：包含RBAC配置、网络策略、Pod安全标准等安全最佳实践 +- **排错指南**：提供常见错误代码排查方法和日志分析技巧 +- **性能优化**：包含资源配额、HPA配置、调度优化等性能调优建议 diff --git a/rules/devops/kubernetes/kubernetes-mkdocs-documentation/documentation-best-practices-rules.mdc b/rules/devops/kubernetes/kubernetes-mkdocs-documentation/documentation-best-practices-rules.mdc index f1de725..c4b2b17 100644 --- a/rules/devops/kubernetes/kubernetes-mkdocs-documentation/documentation-best-practices-rules.mdc +++ b/rules/devops/kubernetes/kubernetes-mkdocs-documentation/documentation-best-practices-rules.mdc @@ -1,9 +1,20 @@ --- -description: 文档最佳实践规则 +description: "Kubernetes文档编写规范，确保技术文档的可读性和可维护性" globs: **/docs/*.md --- -- 每个 Markdown 文件不超过 2000 字 -- 使用二级标题组织内容结构 -- 每段文字配合相关图示或示例 -- 为长文档添加目录(TOC) -- 重要配置项使用警告/注意框突出显示 +- **文档结构**： + - 使用H2标题组织主要章节 + - 每个Markdown文件不超过2000字(约5分钟阅读量) + - 长文档必须包含目录(TOC) +- **内容规范**： + - 每章节开头提供简要概述 + - 技术概念首次出现时需明确定义 + - 配置示例必须包含完整Yaml和注释 +- **格式要求**： + - 使用Mermaid/PlantUML生成架构图 + - 重要警告使用> [!WARNING]语法突出 + - 代码块标注语言类型和适用环境 +- **版本管理**： + - 文档头部包含最后更新时间 + - 重大变更记录在CHANGELOG中 + - 废弃内容标注替代方案 diff --git a/rules/devops/observability/.cursorrules b/rules/devops/observability/.cursorrules index 815c096..fc7180e 100644 --- a/rules/devops/observability/.cursorrules +++ b/rules/devops/observability/.cursorrules @@ -2,15 +2,22 @@ ## 技术栈 -- Metrics -- Logs -- Tracing -- 异常检测 +- **指标(Metrics)**: Prometheus + VictoriaMetrics + Grafana +- **日志(Logs)**: Loki + FluentBit + Elasticsearch +- **追踪(Tracing)**: OpenTelemetry + Jaeger/Tempo +- **告警(Alert)**: Alertmanager + Grafana告警 ## 核心准则 -1. **数据采集**：规范OpenTelemetry标准 -2. **关联分析**：实现跨信号关联 -3. **存储优化**：设计降采样策略 -4. **告警治理**：完善通知路由 -5. **成本控制**：统一数据治理 +1. **统一采集**：实现Metrics/Logs/Tracing三位一体采集 +2. **关联分析**：建立跨信号关联关系(如Trace-to-Logs) +3. **智能基线**：基于历史数据建立动态阈值 +4. **成本控制**：采用智能采样策略减少存储开销 +5. **SLO驱动**：以服务等级目标为导向配置监控 + +## 实施建议 + +- 优先实现关键业务链路100%追踪覆盖 +- 日志采集保留原始上下文信息 +- 指标定义遵循RED方法(Requests/Errors/Duration) +- 告警规则避免过度配置(建议<5条/服务) diff --git a/rules/devops/observability/README.md b/rules/devops/observability/README.md index dc32d9f..11c7c12 100644 --- a/rules/devops/observability/README.md +++ b/rules/devops/observability/README.md @@ -9,7 +9,16 @@ ## 规则特点 -- 支持OpenTelemetry -- 提供关联分析 -- 包含存储优化指南 -- 实现智能告警 +- **统一观测**：整合Metrics/Logs/Tracing三支柱数据 +- **智能告警**：基于机器学习实现异常检测 +- **端到端追踪**：支持分布式事务全链路追踪 +- **成本优化**：智能采样降低存储开销 +- **开放标准**：兼容OpenTelemetry等开放协议 + +## 技术栈 + +- 指标采集：Prometheus/VictoriaMetrics +- 日志分析：Loki/Elasticsearch +- 分布式追踪：Jaeger/Tempo +- 告警管理：Alertmanager/Grafana +- 可视化：Grafana/Kibana diff --git a/rules/devops/python-containerization/.cursorrules b/rules/devops/python-containerization/.cursorrules new file mode 100644 index 0000000..d5aafc1 --- /dev/null +++ b/rules/devops/python-containerization/.cursorrules @@ -0,0 +1,3 @@ +你是 Python、数据库算法和容器化技术方面的专家。 + +遵循 Python 官方文档和 PEPs，以实现 Python 开发的最佳实践。 \ No newline at end of file diff --git a/rules/devops/python-containerization/README.md b/rules/devops/python-containerization/README.md new file mode 100644 index 0000000..75cb7fe --- /dev/null +++ b/rules/devops/python-containerization/README.md @@ -0,0 +1,21 @@ +# Python 容器化 .cursorrules 提示文件 + +作者：Chakshu Gautam + +## 你可以构建什么 +数据库算法游乐场：一个基于 Web 的交互式工具，供学生和开发人员学习和实验 B-树和 MVCC 等数据库算法。用户可以实时可视化和操作数据结构，以了解其操作和性能。Pythonic 代码风格 Linter：一个高级的 Python linter，不仅检查 PEP 8 合规性，还提供实现函数式编程模式和整洁代码实践的建议。它可以与 IDE 集成以提供实时反馈。容器化数据库部署服务：一种自动化数据库应用程序容器化和部署的服务。它使用 Docker 和 Docker Compose 来确保轻量级、高效的部署，用户只需进行最少的配置。并发和并行工作流优化器：旨在帮助开发人员使用 asyncio、multiprocessing 和其他技术，在 Python 应用程序中识别实现并发和并行的最佳方式的工具或库，从而增强 I/O 密集型和 CPU 密集型任务的性能。性能分析仪表板：一个聚合来自 cProfile 的性能分析数据并将其呈现在直观仪表板中的 Web 应用程序，帮助开发人员可视化瓶颈并有效优化其代码。综合单元测试套件：一个即插即用的测试框架，集成了专门针对数据库相关操作的单元测试、集成测试和基于属性的测试。它提供预配置的测试场景以提高代码可靠性。Python 代码片段共享网络：一个社区驱动的平台，供 Python 开发人员分享和发现遵循最佳编码实践的可重用代码片段，包括列表推导、高效数据结构使用的综合示例等。交互式文档生成器：一种通过分析 Python 项目中的类型提示和文档字符串，帮助开发人员自动生成综合 API 文档（包括架构概述和代码示例）的工具。Python 项目的 CI/CD 管道构建器：一种自动化 CI/CD 管道设置的服务，专为 Python 项目量身定制，确保测试、linting 和 Docker 镜像构建完美集成到开发生命周期中。智能查询优化器：一个 SQL 数据库插件，通过分析各种技术（如连接顺序优化）自动优化查询执行计划，从而可能减少执行时间和资源使用。 + +## 优势 +- **模块化设计**：遵循Python的最佳实践，确保代码结构清晰、易于维护和扩展 +- **性能优化**：利用B-树、WAL和MVCC等高效数据库算法，提供卓越的性能表现 +- **容器化支持**：内置Docker和Docker Compose配置，简化部署流程 +- **并发处理**：集成asyncio和multiprocessing技术，优化I/O密集型和CPU密集型任务 +- **全面测试**：提供预配置的测试场景，确保代码质量和可靠性 +- **自动化流程**：支持CI/CD管道自动构建、测试和部署 +- **社区支持**：鼓励代码共享和最佳实践交流，促进知识共享 + +## 简介 +寻求使用 Python 构建高性能、模块化数据库系统的开发人员，将从这个提示中受益，它利用了代码结构、数据库算法、容器化和 CI/CD 管道的最佳实践。 + +## .cursorrules 提示概述 +.cursorrules 文件为在 Python、数据库算法和容器化技术方面具有专业知识的开发人员提供了全面的指南。它概述了编写整洁和模块化 Python 代码的关键实践，遵循 PEP 8 指南并使用函数式编程模式。该文件提供了命名约定、代码结构的标准，并利用 Python 的内置和专用数据结构来提高效率。它详细介绍了 B-树、WAL 和 MVCC 等数据库算法的实现，以及性能优化和测试的策略。涵盖了使用 `asyncio` 和 `multiprocessing` 的并发和并行技术，以及用于部署的基于 Docker 的容器化实践。该文件强调了文档、示例和架构概述的重要性，并建议使用 GitHub Actions 等工具设置 CI/CD 管道以实现自动化流程。它指导开发人员创建文档齐全、高效且可部署的应用程序。 \ No newline at end of file diff --git a/rules/devops/python-containerization/containerization-rules.mdc b/rules/devops/python-containerization/containerization-rules.mdc new file mode 100644 index 0000000..d0a033e --- /dev/null +++ b/rules/devops/python-containerization/containerization-rules.mdc @@ -0,0 +1,6 @@ +--- +description: +globs: +alwaysApply: false +--- +- 遵循创建高效、安全 Dockerfile 的最佳实践。 diff --git a/rules/devops/python-containerization/database-algorithm-rules.mdc b/rules/devops/python-containerization/database-algorithm-rules.mdc new file mode 100644 index 0000000..b93c988 --- /dev/null +++ b/rules/devops/python-containerization/database-algorithm-rules.mdc @@ -0,0 +1,5 @@ +--- +description: +globs: +alwaysApply: false +--- diff --git a/rules/devops/terraform-iac/.cursorrules b/rules/devops/terraform-iac/.cursorrules index 77ff33a..55a6ba7 100644 --- a/rules/devops/terraform-iac/.cursorrules +++ b/rules/devops/terraform-iac/.cursorrules @@ -2,15 +2,33 @@ ## 技术栈 -- Terraform -- Pulumi -- Terragrunt -- CloudFormation +- **核心工具**： + - Terraform 1.5+ (HCL语法) + - Pulumi (多语言支持) + - Terragrunt (环境管理) +- **生态系统**： + - Terraform Registry (模块市场) + - Terraform Cloud (协作平台) + - Atlantis (自动化工作流) ## 核心准则 -1. **模块化设计**：创建可复用的基础设施模块 -2. **状态管理**：规范远程状态存储配置 -3. **变量规范**：使用类型约束的输入变量 -4. **安全实践**：敏感数据使用 Vault 或 KMS 管理 -5. **多环境策略**：实现 dev/stage/prod 环境隔离 +1. **状态管理**： + - 远程状态存储加密 + - 状态文件锁定机制 + - 定期备份策略 +2. **代码组织**： + - 环境隔离(dev/stage/prod) + - 模块化架构设计 + - 清晰的目录结构 +3. **安全合规**： + - 静态代码分析(SAST) + - 动态权限检查 + - 变更影响评估 + +## 实施建议 + +- 使用`terraform validate`验证语法 +- 通过`plan`输出评审变更 +- 小步频繁提交变更 +- 监控漂移(drift)情况 diff --git a/rules/devops/terraform-iac/README.md b/rules/devops/terraform-iac/README.md index 3f046cf..13ff789 100644 --- a/rules/devops/terraform-iac/README.md +++ b/rules/devops/terraform-iac/README.md @@ -13,3 +13,25 @@ - 提供模块版本管理规范 - 包含安全基线配置 (加密/权限/审计) - 实现基础设施变更的自动化测试 + +## 技术栈 + +- **核心工具**：Terraform 1.5+ / Pulumi 3.0+ +- **编排工具**：Terragrunt / Terraform Cloud +- **策略检查**：OPA / Sentinel / Checkov +- **状态管理**：S3 + DynamoDB / Azure Blob Storage + +## 最佳实践 + +1. **模块设计**： + - 单一职责原则 + - 语义化版本控制 + - 完善的README和示例 +2. **安全规范**： + - 敏感变量使用Vault管理 + - 最小权限原则 + - 基础设施变更审计 +3. **多云策略**： + - 抽象Provider配置 + - 统一资源命名规范 + - 跨云账号管理方案 From 8df6622f08cd292388d5dcc338a9fb1fcaa1ba4e Mon Sep 17 00:00:00 2001 From: None Date: Wed, 2 Jul 2025 14:42:09 +0800 Subject: [PATCH 02/19] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E6=8A=80=E6=9C=AF=E6=A0=88=E8=A7=84=E8=8C=83=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E5=8C=85=E5=90=ABReact=E3=80=81Apollo?= =?UTF-8?q?=E3=80=81Chakra=20UI=E5=92=8CMobX=E7=9B=B8=E5=85=B3=E6=8C=87?= =?UTF-8?q?=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../react/apollo-graphql/apollo-caching.mdc | 9 ++- .../apollo-graphql/apollo-custom-hooks.mdc | 31 +++++++- .../react/apollo-graphql/apollo-devtools.mdc | 10 ++- .../apollo-graphql/apollo-provider-setup.mdc | 28 ++++++- .../graphql-apollo-client-usage.mdc | 65 ++++++++++++++-- .../graphql-error-boundaries.mdc | 59 +++++++++++++- .../graphql-naming-conventions.mdc | 29 ++++++- .../graphql-typescript-integration.mdc | 78 ++++++++++++++++++- ...react-functional-components-preference.mdc | 32 +++++++- .../chakra-ui---accessibility-features.mdc | 26 ++++++- .../chakra-ui---component-composition.mdc | 48 +++++++++++- .../chakra-ui---dark-mode-implementation.mdc | 25 +++++- .../chakra-ui---performance-optimization.mdc | 15 +++- .../chakra-ui---responsive-design.mdc | 31 +++++++- .../chakra-ui---semantic-html-rendering.mdc | 23 +++++- .../chakra-ui---theme-directory-rules.mdc | 55 ++++++++++++- .../chakra-ui/chakra-ui-best-practices.mdc | 45 +++++++++-- .../react-chakra-ui---folder-structure.mdc | 34 +++++--- .../react-chakra-ui---general-preferences.mdc | 39 +++++++++- .../react-chakra-ui---typescript-usage.mdc | 30 ++++++- .../frontend/react/mobx/folder-structure.mdc | 30 +++++-- .../react/mobx/mobx-best-practices.mdc | 14 +++- .../react/mobx/mobx-dependency-injection.mdc | 51 +++++++++++- rules/frontend/react/mobx/mobx-devtools.mdc | 45 ++++++++++- .../react/mobx/mobx-react-lite-usage.mdc | 52 ++++++++++++- .../react/mobx/mobx-reaction-usage.mdc | 55 ++++++++++++- rules/frontend/react/nextjs-basic/README.md | 18 +++++ .../nextjs-basic/assistant-response-rules.mdc | 22 ++++-- .../nextjs-basic/backend-stack-rules.mdc | 10 ++- .../nextjs-basic/coding-process-rules.mdc | 12 +-- .../react/nextjs-basic/coding-style-rules.mdc | 25 +++++- .../react/nextjs-basic/editing-code-rules.mdc | 8 +- .../nextjs-basic/frontend-stack-rules.mdc | 15 ++-- .../nextjs-basic/general-assistant-rules.mdc | 12 ++- .../history-and-next-task-rules.mdc | 11 ++- .../nextjs-basic/llm-integration-rules.mdc | 10 ++- 36 files changed, 985 insertions(+), 117 deletions(-) diff --git a/rules/frontend/react/apollo-graphql/apollo-caching.mdc b/rules/frontend/react/apollo-graphql/apollo-caching.mdc index 30c9dc6..f5482c1 100644 --- a/rules/frontend/react/apollo-graphql/apollo-caching.mdc +++ b/rules/frontend/react/apollo-graphql/apollo-caching.mdc @@ -1,5 +1,10 @@ --- -description: 利用 Apollo Client 的缓存功能来提高性能。 +description: "利用 Apollo Client 的缓存功能来提高性能" globs: src/**/*.js --- -- 利用 Apollo Client 的缓存功能 +- **利用 Apollo Client 的缓存功能**： + - 优先使用 Apollo Client 的规范化缓存（Normalized Cache）来存储和管理数据，减少不必要的网络请求。 + - 理解并配置 `fetchPolicy`，以优化数据获取策略，例如 `cache-first`、`network-only`、`cache-and-network` 等。 + - 针对频繁变动的数据，考虑使用 `no-cache` 或 `cache-and-network` 策略，并结合订阅（Subscriptions）或轮询（Polling）实现实时更新。 + - 对于列表数据，合理使用 `offsetLimitPagination` 或 `cursorPagination` 等策略来处理分页和无限滚动，确保缓存的有效性。 + - 在进行数据修改（如 Mutations）后，通过 `update` 函数或 `refetchQueries` 来及时更新缓存，保持UI与后端数据的一致性。 diff --git a/rules/frontend/react/apollo-graphql/apollo-custom-hooks.mdc b/rules/frontend/react/apollo-graphql/apollo-custom-hooks.mdc index f57b601..1f869e4 100644 --- a/rules/frontend/react/apollo-graphql/apollo-custom-hooks.mdc +++ b/rules/frontend/react/apollo-graphql/apollo-custom-hooks.mdc @@ -1,5 +1,32 @@ --- -description: 指导为 Apollo 操作实现自定义 hooks。 +description: "指导为 Apollo 操作实现自定义 hooks" globs: src/hooks/**/*.js --- -- 为 Apollo 操作实现自定义 hooks +- **为 Apollo 操作实现自定义 hooks**： + - **封装复杂逻辑**：将重复的 Apollo Client 操作（如查询、变更、订阅）和相关逻辑封装到自定义 hooks 中，提高代码复用性。 + - **统一错误处理和加载状态**：在自定义 hooks 中统一处理加载（`loading`）、错误（`error`）状态和数据（`data`），简化组件层的逻辑。 + - **类型安全**：结合 TypeScript 为自定义 hooks 定义清晰的输入（变量）和输出（数据、状态）类型，确保类型安全。 + - **可测试性**：设计易于测试的自定义 hooks，方便进行单元测试和集成测试。 + - **示例**： + ```typescript + // hooks/useUser.ts + import { useQuery, gql } from '@apollo/client'; + + const GET_USER_QUERY = gql` + query GetUser($id: ID!) { + user(id: $id) { + id + name + email + } + } + `; + + export const useUser = (id: string) => { + const { data, loading, error } = useQuery(GET_USER_QUERY, { + variables: { id }, + }); + + return { user: data?.user, loading, error }; + }; + ``` diff --git a/rules/frontend/react/apollo-graphql/apollo-devtools.mdc b/rules/frontend/react/apollo-graphql/apollo-devtools.mdc index eb16e7c..55c8391 100644 --- a/rules/frontend/react/apollo-graphql/apollo-devtools.mdc +++ b/rules/frontend/react/apollo-graphql/apollo-devtools.mdc @@ -1,5 +1,11 @@ --- -description: 建议使用 Apollo Client DevTools 进行调试。 +description: "建议使用 Apollo Client DevTools 进行调试" globs: src/**/*.js --- -- 使用 Apollo Client DevTools 进行调试 +- **使用 Apollo Client DevTools 进行调试**： + - **安装与集成**：在开发环境中安装并集成 Apollo Client DevTools 浏览器扩展，以便于调试 Apollo Client 的操作和缓存状态。 + - **查询与变更监控**：利用 DevTools 监控所有 GraphQL 查询（Queries）、变更（Mutations）和订阅（Subscriptions）的请求与响应，包括变量、操作名称和返回数据。 + - **缓存检查**：检查 Apollo Client 的规范化缓存（Normalized Cache）内容，理解数据如何存储、更新和失效，有助于排查数据不一致问题。 + - **性能分析**：分析 GraphQL 请求的性能，识别潜在的瓶颈，例如慢查询或过多的网络请求。 + - **错误诊断**：查看 GraphQL 错误信息，快速定位后端或前端数据处理中的问题。 + - **状态管理**：观察组件如何与 Apollo Client 交互，以及数据流如何在应用中传递。 diff --git a/rules/frontend/react/apollo-graphql/apollo-provider-setup.mdc b/rules/frontend/react/apollo-graphql/apollo-provider-setup.mdc index 765a204..9ef1871 100644 --- a/rules/frontend/react/apollo-graphql/apollo-provider-setup.mdc +++ b/rules/frontend/react/apollo-graphql/apollo-provider-setup.mdc @@ -1,5 +1,29 @@ --- -description: 要求在应用程序根部使用 Apollo Provider。 +description: "要求在应用程序根部使用 Apollo Provider" globs: src/App.jsx --- -- 在应用程序根部使用 Apollo Provider +- **在应用程序根部使用 Apollo Provider**： + - **全局可用性**：确保在 React 应用程序的根组件（例如 `App.js` 或 `index.js`）中使用 `ApolloProvider` 包裹整个应用，以便所有子组件都能访问 Apollo Client 实例。 + - **Client 实例配置**：在 `ApolloProvider` 中传入已配置好的 `ApolloClient` 实例，该实例应包含 `uri`（GraphQL 服务器地址）和 `cache`（缓存策略，通常是 `InMemoryCache`）等必要配置。 + - **示例**： + ```javascript + // index.js 或 App.js + import React from 'react'; + import ReactDOM from 'react-dom/client'; + import { ApolloClient, InMemoryCache, ApolloProvider, gql } from '@apollo/client'; + import App from './App'; + + const client = new ApolloClient({ + uri: 'YOUR_GRAPHQL_ENDPOINT', + cache: new InMemoryCache(), + }); + + ReactDOM.createRoot(document.getElementById('root')).render( + + + + + , + ); + ``` + - **中间件与错误处理**：在 `ApolloClient` 配置中，可以添加 `link` 来处理认证、错误重试、文件上传等高级功能，例如使用 `HttpLink`、`AuthLink`、`ErrorLink` 等。 diff --git a/rules/frontend/react/apollo-graphql/graphql-apollo-client-usage.mdc b/rules/frontend/react/apollo-graphql/graphql-apollo-client-usage.mdc index 8056a26..5c65386 100644 --- a/rules/frontend/react/apollo-graphql/graphql-apollo-client-usage.mdc +++ b/rules/frontend/react/apollo-graphql/graphql-apollo-client-usage.mdc @@ -1,9 +1,62 @@ --- -description: 应用 GraphQL 和 Apollo Client 使用的最佳实践，包括状态管理、数据获取和错误处理。 +description: "应用 GraphQL 和 Apollo Client 使用的最佳实践，包括状态管理、数据获取和错误处理" globs: src/graphql/**/*.js --- -- 使用 Apollo Client 进行状态管理和数据获取 -- 实现查询组件进行数据获取 -- 利用变更操作进行数据修改 -- 使用片段创建可重用的查询部分 -- 实现适当的错误处理和加载状态 +- **使用 Apollo Client 进行状态管理和数据获取**： + - 利用 `useQuery` Hook 进行数据查询，处理加载状态、错误和数据。 + - 使用 `useMutation` Hook 执行数据修改操作，并在成功后更新缓存或重新获取相关数据。 + - 结合 `useSubscription` Hook 实现实时数据更新。 +- **实现查询组件进行数据获取**： + - 推荐使用基于 Hook 的方式（如 `useQuery`）而非旧版 `Query` 组件，以更好地利用 React Hooks 的特性。 + - 示例： + ```typescript + import { useQuery, gql } from '@apollo/client'; + + const GET_TODOS = gql` + query GetTodos { + todos { + id + text + completed + } + } + `; + + function TodosList() { + const { loading, error, data } = useQuery(GET_TODOS); + + if (loading) return

Loading...

; + if (error) return

Error :({error.message}

; + + return ( + + ); + } + ``` +- **利用变更操作进行数据修改**： + - 使用 `useMutation` Hook 发送变更请求，并利用 `update` 函数或 `refetchQueries` 选项在变更成功后更新 Apollo 缓存，确保 UI 状态与后端数据同步。 +- **使用片段创建可重用的查询部分**： + - 定义 GraphQL 片段（Fragments）来封装可重用的字段集，提高查询的可维护性和复用性。 + - 示例： + ```graphql + fragment UserFields on User { + id + name + email + } + + query GetUserDetails($id: ID!) { + user(id: $id) { + ...UserFields + } + } + ``` +- **实现适当的错误处理和加载状态**： + - 在组件中处理 `loading` 和 `error` 状态，向用户提供友好的加载指示和错误反馈。 + - 可以结合 `ErrorLink` 或自定义错误边界（Error Boundaries）来集中处理 GraphQL 错误。 diff --git a/rules/frontend/react/apollo-graphql/graphql-error-boundaries.mdc b/rules/frontend/react/apollo-graphql/graphql-error-boundaries.mdc index fd798a1..c48ef23 100644 --- a/rules/frontend/react/apollo-graphql/graphql-error-boundaries.mdc +++ b/rules/frontend/react/apollo-graphql/graphql-error-boundaries.mdc @@ -1,5 +1,58 @@ --- -description: 要求为 GraphQL 错误实现适当的错误边界。 +description: "要求为 GraphQL 错误实现适当的错误边界" globs: src/**/*.jsx ---- -- 为 GraphQL 错误实现适当的错误边界 +--- +- **为 GraphQL 错误实现适当的错误边界**： + - **使用 React 错误边界**：利用 React 的错误边界（Error Boundaries）来捕获组件树中由 GraphQL 操作（查询、变更、订阅）引起的 JavaScript 错误，防止整个应用崩溃。 + - **集中错误处理**：在错误边界组件中集中处理和展示友好的错误信息，而不是让每个组件单独处理错误状态。 + - **错误日志记录**：在错误边界中实现错误日志记录机制（例如，发送到 Sentry、Bugsnag 等错误监控服务），以便于跟踪和诊断生产环境中的问题。 + - **用户体验**：当发生错误时，向用户显示一个回退 UI，提供重试选项或引导用户进行下一步操作，提升用户体验。 + - **示例**： + ```javascript + // ErrorBoundary.js + import React from 'react'; + + class ErrorBoundary extends React.Component { + constructor(props) { + super(props); + this.state = { hasError: false, error: null, errorInfo: null }; + } + + static getDerivedStateFromError(error) { + // 更新 state 使下一次渲染能够显示降级后的 UI + return { hasError: true }; + } + + componentDidCatch(error, errorInfo) { + // 你同样可以将错误日志上报给服务器 + console.error("Uncaught error:", error, errorInfo); + this.setState({ error, errorInfo }); + } + + render() { + if (this.state.hasError) { + // 你可以自定义降级后的 UI 并渲染 + return ( +
+

Something went wrong.

+
+ {this.state.error && this.state.error.toString()} +
+ {this.state.errorInfo.componentStack} +
+
+ ); + } + + return this.props.children; + } + } + + export default ErrorBoundary; + + // 在应用中使用 + // + // + // + ``` + - **与 Apollo Link 结合**：对于 GraphQL 网络层面的错误（如 HTTP 错误、GraphQL 格式错误），可以结合 Apollo Client 的 `ErrorLink` 进行处理，并在 `ErrorLink` 中抛出错误，使其能被 React 错误边界捕获。 diff --git a/rules/frontend/react/apollo-graphql/graphql-naming-conventions.mdc b/rules/frontend/react/apollo-graphql/graphql-naming-conventions.mdc index 9a40cc4..15077f8 100644 --- a/rules/frontend/react/apollo-graphql/graphql-naming-conventions.mdc +++ b/rules/frontend/react/apollo-graphql/graphql-naming-conventions.mdc @@ -1,5 +1,30 @@ --- -description: 要求遵循查询、变更和片段的命名约定。 +description: "要求遵循查询、变更和片段的命名约定" globs: src/graphql/**/*.js --- -- 遵循查询、变更和片段的命名约定 +- **遵循查询、变更和片段的命名约定**： + - **查询（Queries）**： + - 使用 `get` 或 `fetch` 前缀，后跟实体名称和可选的复数形式。 + - 示例：`getUsers`、`getUserById`、`fetchProductDetails`。 + - **变更（Mutations）**： + - 使用动词前缀表示操作类型，后跟实体名称。 + - 示例：`createUser`、`updateProduct`、`deleteComment`。 + - **订阅（Subscriptions）**： + - 使用 `on` 前缀，后跟事件名称。 + - 示例：`onNewMessage`、`onUserUpdated`。 + - **片段（Fragments）**： + - 使用实体名称，后跟 `Fields` 或 `Details` 后缀。 + - 示例：`UserFields`、`ProductDetails`。 + - **类型（Types）和字段（Fields）**： + - 类型名称使用 PascalCase（大驼峰命名法）。 + - 字段名称使用 camelCase（小驼峰命名法）。 + - 示例：`User` 类型中的 `firstName` 字段。 + - **枚举（Enums）**： + - 枚举类型名称使用 PascalCase，枚举值使用 ALL_CAPS（全大写）。 + - 示例：`OrderStatus` 枚举中的 `PENDING`、`COMPLETED`。 + - **变量（Variables）**： + - 变量名称使用 camelCase。 + - 示例：`$userId`、`$input`。 + - **通用原则**： + - 保持命名清晰、简洁、一致，能够直观地表达其用途和所操作的数据。 + - 避免缩写，除非是广为人知的缩写（如 `ID`）。 diff --git a/rules/frontend/react/apollo-graphql/graphql-typescript-integration.mdc b/rules/frontend/react/apollo-graphql/graphql-typescript-integration.mdc index 9380950..c0c31c6 100644 --- a/rules/frontend/react/apollo-graphql/graphql-typescript-integration.mdc +++ b/rules/frontend/react/apollo-graphql/graphql-typescript-integration.mdc @@ -1,5 +1,79 @@ --- -description: 强制使用 TypeScript 确保 GraphQL 操作的类型安全。 +description: "强制使用 TypeScript 确保 GraphQL 操作的类型安全" globs: src/graphql/**/*.ts --- -- 对 GraphQL 操作使用 TypeScript 确保类型安全 +- **对 GraphQL 操作使用 TypeScript 确保类型安全**： + - **代码生成**：利用 GraphQL Code Generator 或类似工具，根据 GraphQL schema 和操作（Queries, Mutations, Subscriptions）自动生成 TypeScript 类型定义。 + - **类型推断**：确保 `useQuery`、`useMutation` 和 `useSubscription` Hooks 的返回值（`data`, `loading`, `error`）和变量（`variables`）都具有正确的类型推断。 + - **端到端类型安全**：从 GraphQL API 到前端组件，实现端到端的类型安全，减少运行时错误。 + - **示例**： + ```typescript + // graphql.schema.json (部分) + { + "data": { + "__schema": { + "types": [ + { + "kind": "OBJECT", + "name": "User", + "fields": [ + { "name": "id", "type": { "kind": "NON_NULL", "ofType": { "kind": "SCALAR", "name": "ID" } } }, + { "name": "name", "type": { "kind": "SCALAR", "name": "String" } } + ] + } + ] + } + } + } + + // query.graphql + query GetUser($id: ID!) { + user(id: $id) { + id + name + } + } + + // generated.ts (通过工具生成) + export type GetUserQueryVariables = { + id: string; + }; + + export type GetUserQuery = { + user?: { + __typename?: "User"; + id: string; + name?: string | null; + } | null; + }; + + // component.tsx + import { useQuery } from '@apollo/client'; + import { GetUserQuery, GetUserQueryVariables } from './generated'; // 假设类型已生成 + + const GET_USER_QUERY = gql` + query GetUser($id: ID!) { + user(id: $id) { + id + name + } + } + `; + + function UserProfile({ userId }: { userId: string }) { + const { data, loading, error } = useQuery(GET_USER_QUERY, { + variables: { id: userId }, + }); + + if (loading) return

Loading...

; + if (error) return

Error: {error.message}

; + + return ( +
+

{data?.user?.name}

+

ID: {data?.user?.id}

+
+ ); + } + ``` + - **手动类型定义（不推荐）**：在无法使用代码生成工具的情况下，可以手动定义 GraphQL 响应的 TypeScript 接口，但这容易出错且难以维护。 diff --git a/rules/frontend/react/apollo-graphql/react-functional-components-preference.mdc b/rules/frontend/react/apollo-graphql/react-functional-components-preference.mdc index ddb19df..66414c3 100644 --- a/rules/frontend/react/apollo-graphql/react-functional-components-preference.mdc +++ b/rules/frontend/react/apollo-graphql/react-functional-components-preference.mdc @@ -1,5 +1,33 @@ --- -description: 在 React 组件中强制使用带有 hooks 的函数式组件。 +description: "在 React 组件中强制使用带有 hooks 的函数式组件" globs: src/components/**/*.jsx --- -- 始终使用带有 hooks 的函数式组件而不是类组件。 +- **始终使用带有 hooks 的函数式组件而不是类组件**： + - **现代化开发**：优先使用 React Hooks（如 `useState`, `useEffect`, `useContext`, `useReducer`, `useCallback`, `useMemo` 等）进行状态管理和副作用处理，以符合 React 官方推荐的现代化开发范式。 + - **代码简洁性**：函数式组件通常比类组件更简洁，更易于阅读和理解，尤其是在处理逻辑复用时。 + - **逻辑复用**：通过自定义 Hooks，可以方便地在不同组件之间共享状态逻辑，避免了高阶组件（HOCs）和渲染属性（Render Props）带来的嵌套问题。 + - **性能优化**：结合 `useCallback` 和 `useMemo` 等 Hooks，可以有效地进行性能优化，避免不必要的渲染。 + - **可测试性**：函数式组件和 Hooks 更容易进行单元测试。 + - **示例**： + ```javascript + // 函数式组件示例 + import React, { useState, useEffect } from 'react'; + + function Counter() { + const [count, setCount] = useState(0); + + useEffect(() => { + document.title = `You clicked ${count} times`; + }, [count]); + + return ( +
+

You clicked {count} times

+ +
+ ); + } + ``` + - **特殊情况**：仅在极少数需要使用 `getSnapshotBeforeUpdate` 或 `componentDidCatch` 等生命周期方法时，才考虑使用类组件，但大多数场景下 Hooks 都能提供替代方案（如错误边界）。 diff --git a/rules/frontend/react/chakra-ui/chakra-ui---accessibility-features.mdc b/rules/frontend/react/chakra-ui/chakra-ui---accessibility-features.mdc index 4ddc037..75a6f8f 100644 --- a/rules/frontend/react/chakra-ui/chakra-ui---accessibility-features.mdc +++ b/rules/frontend/react/chakra-ui/chakra-ui---accessibility-features.mdc @@ -1,5 +1,27 @@ --- -description: 使用 Chakra UI 构建的 React 组件的可访问性功能。 +description: "使用 Chakra UI 构建的 React 组件的可访问性功能" globs: src/**/*.* --- -- 利用 Chakra UI 的内置可访问性功能 +- **利用 Chakra UI 的内置可访问性功能**： + - **语义化 HTML**：优先使用 Chakra UI 提供的组件，它们通常会渲染出语义化的 HTML 元素，有助于提高可访问性。 + - **WAI-ARIA 支持**：Chakra UI 组件内置了 WAI-ARIA 属性，如 `aria-label`、`aria-labelledby`、`aria-describedby` 等，确保辅助技术能够正确解释组件。 + - **键盘导航**：所有交互式组件都应支持键盘导航，确保用户可以通过键盘（Tab、Enter、Space 等）进行操作。 + - **焦点管理**：在模态框、抽屉、菜单等组件中，确保焦点管理正确，例如打开时将焦点移到内容区域，关闭时将焦点返回到触发元素。 + - **颜色对比度**：在设计自定义主题或使用颜色时，确保文本和背景之间有足够高的颜色对比度，以满足 WCAG 2.1 AA 级标准。 + - **可访问性属性定制**：在必要时，可以通过 `aria-` 和 `data-` 属性来自定义组件的可访问性行为。 + - **示例**： + ```jsx + import { Button } from '@chakra-ui/react'; + + function MyAccessibleButton() { + return ( + + ); + } + ``` + - **测试**：在开发过程中，使用可访问性测试工具（如 Lighthouse、axe-core）和屏幕阅读器（如 NVDA、JAWS）进行测试，确保应用的可访问性。 diff --git a/rules/frontend/react/chakra-ui/chakra-ui---component-composition.mdc b/rules/frontend/react/chakra-ui/chakra-ui---component-composition.mdc index 9f4dfc0..610e277 100644 --- a/rules/frontend/react/chakra-ui/chakra-ui---component-composition.mdc +++ b/rules/frontend/react/chakra-ui/chakra-ui---component-composition.mdc @@ -1,5 +1,49 @@ --- -description: 确保使用 Chakra UI 组件以可组合的方式构建 React 组件。 +description: "确保使用 Chakra UI 组件以可组合的方式构建 React 组件" globs: src/components/**/*.* --- -- 使用 Chakra UI 实现适当的组件组合 +- **使用 Chakra UI 实现适当的组件组合**： + - **利用 `as` prop**：Chakra UI 组件支持 `as` prop，允许将组件渲染为不同的 HTML 元素或 React 组件，这在构建灵活的 UI 时非常有用。 + - **扩展现有组件**：通过直接传递 Chakra UI 组件的 props 来扩展其样式和行为，而不是重新创建组件。 + - **自定义组件的封装**：将复杂的 UI 逻辑和样式封装在自定义组件中，并使用 `Box`、`Flex`、`Stack` 等布局组件进行组合，保持组件的单一职责和可复用性。 + - **使用 `forwardRef`**：当自定义组件需要转发 ref 时，使用 `forwardRef` 确保其与 Chakra UI 组件的兼容性。 + - **示例**： + ```jsx + import { Box, Flex, Text, Button } from '@chakra-ui/react'; + + function Card({ title, description, buttonText, ...rest }) { + return ( + + + + {title} + + + {description} + + + ); + } + + // 使用示例 + function MyPage() { + return ( + + + + + ); + } + ``` + - **避免过度封装**：在某些情况下，直接使用 Chakra UI 的原子组件可能比创建新的自定义组件更有效，避免不必要的抽象。 diff --git a/rules/frontend/react/chakra-ui/chakra-ui---dark-mode-implementation.mdc b/rules/frontend/react/chakra-ui/chakra-ui---dark-mode-implementation.mdc index efc4632..6cafb8a 100644 --- a/rules/frontend/react/chakra-ui/chakra-ui---dark-mode-implementation.mdc +++ b/rules/frontend/react/chakra-ui/chakra-ui---dark-mode-implementation.mdc @@ -1,5 +1,26 @@ --- -description: 在构建 React 组件时使用 Chakra UI 的颜色模式实现暗模式。 +description: "在构建 React 组件时使用 Chakra UI 的颜色模式实现暗模式" globs: src/**/*.* --- -- 使用 Chakra UI 的颜色模式实现暗模式 +- **使用 Chakra UI 的颜色模式实现暗模式**： + - **自动颜色模式**：利用 Chakra UI 内置的颜色模式（Color Mode）功能，轻松实现亮/暗模式切换，并支持系统偏好设置。 + - **`useColorMode` Hook**：在组件中使用 `useColorMode` Hook 来获取当前颜色模式和切换模式的函数。 + - **`ColorModeScript`**：在应用的根部（例如 `_document.js` 或 `index.js`）引入 `ColorModeScript`，以防止页面加载时的闪烁问题。 + - **主题配置**：在 Chakra UI 主题中定义 `colors` 对象，为亮/暗模式提供不同的颜色值，确保组件在不同模式下显示正确。 + - **示例**： + ```jsx + import { useColorMode, Button, Box } from '@chakra-ui/react'; + + function ColorModeSwitcher() { + const { colorMode, toggleColorMode } = useColorMode(); + return ( + + + + ); + } + ``` + - **持久化**：Chakra UI 默认会将颜色模式偏好存储在 localStorage 中，确保用户下次访问时保持一致。 + - **可访问性**：确保亮/暗模式切换时，颜色对比度仍然满足可访问性标准。 diff --git a/rules/frontend/react/chakra-ui/chakra-ui---performance-optimization.mdc b/rules/frontend/react/chakra-ui/chakra-ui---performance-optimization.mdc index 82266cd..3e998dd 100644 --- a/rules/frontend/react/chakra-ui/chakra-ui---performance-optimization.mdc +++ b/rules/frontend/react/chakra-ui/chakra-ui---performance-optimization.mdc @@ -1,5 +1,16 @@ --- -description: 遵循 Chakra UI 最佳实践来优化 React 组件的性能。 +description: "遵循 Chakra UI 最佳实践来优化 React 组件的性能" globs: src/**/*.* --- -- 遵循 Chakra UI 性能优化的最佳实践 +- **遵循 Chakra UI 性能优化的最佳实践**： + - **按需导入组件**：只导入和使用实际需要的 Chakra UI 组件，避免全量导入，减少打包体积。 + - **避免不必要的重新渲染**： + - 使用 `React.memo` 包装纯函数组件，当 props 没有改变时避免重新渲染。 + - 使用 `useCallback` 和 `useMemo` 优化函数和计算结果，防止它们在每次渲染时重新创建。 + - **CSS 变量**：Chakra UI 内部大量使用 CSS 变量，这有助于减少运行时计算，提高样式更新效率。 + - **主题定制**：在主题配置中，只覆盖需要修改的部分，避免不必要的深度合并。 + - **列表虚拟化**：对于长列表，考虑使用 `react-window` 或 `react-virtualized` 等库进行虚拟化，只渲染视口内的项目，提高性能。 + - **懒加载**：对于不立即需要的组件或模块，使用 `React.lazy` 和 `Suspense` 进行代码分割和懒加载。 + - **避免在渲染函数中创建对象/函数**：避免在组件的渲染函数内部创建新的对象或函数，这会导致每次渲染都创建新的引用，可能导致子组件不必要的重新渲染。 + - **使用 `shouldForwardProp`**：如果自定义组件接收到非标准 HTML 属性，可以使用 `shouldForwardProp` 来防止这些属性被渲染到 DOM 中，避免不必要的 DOM 属性。 + - **服务器端渲染（SSR）/静态站点生成（SSG）**：对于 Next.js 或 Gatsby 等框架，利用 SSR/SSG 预渲染页面，减少客户端加载时间，提高首次内容绘制（FCP）性能。 diff --git a/rules/frontend/react/chakra-ui/chakra-ui---responsive-design.mdc b/rules/frontend/react/chakra-ui/chakra-ui---responsive-design.mdc index c9a32f6..20b27f2 100644 --- a/rules/frontend/react/chakra-ui/chakra-ui---responsive-design.mdc +++ b/rules/frontend/react/chakra-ui/chakra-ui---responsive-design.mdc @@ -1,5 +1,32 @@ --- -description: 利用 Chakra UI 的布局组件在 React 应用程序中创建响应式设计。 +description: "利用 Chakra UI 的布局组件在 React 应用程序中创建响应式设计" globs: src/**/*.* --- -- 使用 Chakra UI 的布局组件进行响应式设计 +- **使用 Chakra UI 的布局组件进行响应式设计**： + - **响应式样式**：利用 Chakra UI 的响应式样式语法，通过数组或对象语法为不同断点（breakpoints）应用不同的样式。 + - **断点定制**：在主题配置中定制或扩展默认断点，以适应项目特定的设计需求。 + - **布局组件**：使用 `Box`、`Flex`、`Grid`、`Stack` 等布局组件构建灵活的响应式布局。 + - **`useBreakpointValue` Hook**：使用 `useBreakpointValue` Hook 根据当前断点动态地选择值。 + - **示例**： + ```jsx + import { Box, Flex, Text, useBreakpointValue } from '@chakra-ui/react'; + + function ResponsiveLayout() { + const columns = useBreakpointValue({ base: 1, md: 2, lg: 3 }); + + return ( + + + This text changes size based on screen width. + + + Column 1 + Column 2 + {columns > 2 && Column 3} + + + ); + } + ``` + - **隐藏/显示组件**：使用 `display` 属性的响应式值（如 `display={{ base: 'none', md: 'block' }}`）来控制组件在不同断点下的显示与隐藏。 + - **可访问性**：确保响应式设计在不同屏幕尺寸和设备上都能保持良好的可访问性。 diff --git a/rules/frontend/react/chakra-ui/chakra-ui---semantic-html-rendering.mdc b/rules/frontend/react/chakra-ui/chakra-ui---semantic-html-rendering.mdc index 53e9db9..03499bd 100644 --- a/rules/frontend/react/chakra-ui/chakra-ui---semantic-html-rendering.mdc +++ b/rules/frontend/react/chakra-ui/chakra-ui---semantic-html-rendering.mdc @@ -1,5 +1,24 @@ --- -description: 在使用 Chakra UI 组件时使用 'as' prop 进行语义化 HTML 渲染。 +description: "在使用 Chakra UI 组件时使用 'as' prop 进行语义化 HTML 渲染" globs: src/components/**/*.* --- -- 使用 'as' prop 进行语义化 HTML 渲染 +- **使用 `as` prop 进行语义化 HTML 渲染**： + - **增强可访问性**：优先使用 Chakra UI 组件的 `as` prop 来渲染正确的语义化 HTML 元素，而不是使用通用的 `Box` 或 `Flex` 组件来替代。 + - **搜索引擎优化（SEO）**：语义化 HTML 有助于搜索引擎更好地理解页面结构和内容，从而提高 SEO 排名。 + - **代码可读性**：使用具有明确语义的 HTML 标签可以提高代码的可读性和可维护性。 + - **示例**： + ```jsx + import { Text, Box, Button } from '@chakra-ui/react'; + + function SemanticExample() { + return ( + + Section Title + This is a paragraph of text within the section. + + + ); + } + ``` + - **避免滥用 `as` prop**：仅在需要改变组件渲染的底层 HTML 元素时使用 `as` prop，而不是为了样式目的而滥用。 + - **保持一致性**：在整个项目中保持语义化 HTML 渲染的一致性，确保所有开发人员都遵循相同的最佳实践。 diff --git a/rules/frontend/react/chakra-ui/chakra-ui---theme-directory-rules.mdc b/rules/frontend/react/chakra-ui/chakra-ui---theme-directory-rules.mdc index 1c14c1a..c68d773 100644 --- a/rules/frontend/react/chakra-ui/chakra-ui---theme-directory-rules.mdc +++ b/rules/frontend/react/chakra-ui/chakra-ui---theme-directory-rules.mdc @@ -1,7 +1,54 @@ --- -description: 主题目录的特定规则，用于管理和自定义 Chakra UI 主题。 +description: "主题目录的特定规则，用于管理和自定义 Chakra UI 主题" globs: src/theme/**/*.* --- -- 创建 theme/index.js 来导出主题 -- 将主题基础放在 theme/foundations/ 中 -- 将组件特定的主题覆盖放在 theme/components/ 中 +- **主题目录的特定规则，用于管理和自定义 Chakra UI 主题**： + - **创建 `theme/index.js` 来导出主题**： + - 所有的主题配置都应集中在 `theme/index.js` 文件中，并从这里导出最终的主题对象。 + - 示例： + ```javascript + // theme/index.js + import { extendTheme } from '@chakra-ui/react'; + import { colors } from './foundations/colors'; + import { Button } from './components/Button'; + + const theme = extendTheme({ + colors, + components: { + Button, + }, + }); + + export default theme; + ``` + - **将主题基础放在 `theme/foundations/` 中**： + - 基础主题设置，如颜色（`colors.js`）、字体（`fonts.js`）、间距（`space.js`）等，应组织在 `theme/foundations/` 目录下。 + - 示例： + ```javascript + // theme/foundations/colors.js + export const colors = { + brand: { + 900: '#1a365d', + 800: '#153e75', + 700: '#2a69ac', + }, + }; + ``` + - **将组件特定的主题覆盖放在 `theme/components/` 中**： + - 对特定 Chakra UI 组件的样式覆盖和变体定义，应组织在 `theme/components/` 目录下，每个组件一个文件。 + - 示例： + ```javascript + // theme/components/Button.js + export const Button = { + baseStyle: { + fontWeight: 'bold', + }, + variants: { + solid: (props) => ({ + bg: props.colorMode === 'dark' ? 'brand.700' : 'brand.500', + color: 'white', + }), + }, + }; + ``` + - **模块化和可维护性**：这种结构有助于保持主题配置的模块化、可读性和可维护性，特别是在大型项目中。 diff --git a/rules/frontend/react/chakra-ui/chakra-ui-best-practices.mdc b/rules/frontend/react/chakra-ui/chakra-ui-best-practices.mdc index 528aa63..a85e3d0 100644 --- a/rules/frontend/react/chakra-ui/chakra-ui-best-practices.mdc +++ b/rules/frontend/react/chakra-ui/chakra-ui-best-practices.mdc @@ -1,9 +1,42 @@ --- -description: 强制执行 Chakra UI 最佳实践以保持一致性并利用框架的功能。 +description: "强制执行 Chakra UI 最佳实践以保持一致性并利用框架的功能" globs: src/**/*.* --- -- 在应用程序根部使用 ChakraProvider -- 利用 Chakra UI 组件实现一致的设计 -- 实现自定义主题以进行品牌特定的样式设计 -- 使用 Chakra UI 断点系统的响应式样式 -- 利用 Chakra UI hooks 增强功能 +- **在应用程序根部使用 `ChakraProvider`**： + - 确保在 React 应用程序的根组件中包裹 `ChakraProvider`，以便所有 Chakra UI 组件都能访问主题和上下文。 + - 示例： + ```jsx + import { ChakraProvider } from '@chakra-ui/react'; + import customTheme from './theme'; // 假设你的主题文件在 './theme/index.js' + + function App() { + return ( + + {/* 你的应用程序内容 */} + + ); + } + ``` +- **利用 Chakra UI 组件实现一致的设计**： + - 优先使用 Chakra UI 提供的组件来构建 UI，而不是编写自定义 CSS，以确保设计的一致性和可维护性。 + - 充分利用其内置的样式 props 和组合能力。 +- **实现自定义主题以进行品牌特定的样式设计**： + - 通过 `extendTheme` 函数定制颜色、字体、间距、组件样式等，以匹配品牌指南。 + - 将主题配置分解为模块化文件（如 `foundations` 和 `components` 目录），提高可组织性。 +- **使用 Chakra UI 断点系统的响应式样式**： + - 利用 Chakra UI 的响应式样式语法（数组或对象语法）来轻松实现跨设备的响应式布局和样式。 + - 示例：`fontSize={{ base: 'md', md: 'lg', lg: 'xl' }}`。 +- **利用 Chakra UI hooks 增强功能**： + - 使用 `useDisclosure` 管理模态框、抽屉等的打开/关闭状态。 + - 使用 `useToast` 显示通知。 + - 使用 `useBreakpointValue` 根据断点获取值。 + - 使用 `useColorMode` 管理亮/暗模式。 +- **可访问性**： + - 始终关注可访问性，利用 Chakra UI 内置的 WAI-ARIA 支持和语义化 HTML 渲染。 + - 确保键盘导航、焦点管理和颜色对比度符合标准。 +- **性能优化**： + - 按需导入组件，避免不必要的重新渲染（使用 `React.memo`、`useCallback`、`useMemo`）。 + - 对于长列表，考虑使用虚拟化。 +- **组件组合**： + - 善用 `as` prop 来改变组件渲染的底层 HTML 元素，实现语义化。 + - 将复杂逻辑封装在自定义组件中，并使用 Chakra UI 的布局组件进行组合。 diff --git a/rules/frontend/react/chakra-ui/react-chakra-ui---folder-structure.mdc b/rules/frontend/react/chakra-ui/react-chakra-ui---folder-structure.mdc index 67124ee..ae29d0f 100644 --- a/rules/frontend/react/chakra-ui/react-chakra-ui---folder-structure.mdc +++ b/rules/frontend/react/chakra-ui/react-chakra-ui---folder-structure.mdc @@ -1,15 +1,25 @@ --- -description: 维护 React 和 Chakra UI 项目的定义文件夹结构以确保代码组织有序。 +description: "维护 React 和 Chakra UI 项目的定义文件夹结构以确保代码组织有序" globs: src/**/*.* --- -- 遵循以下文件夹结构： - -src/ - components/ - pages/ - theme/ - index.js - foundations/ - components/ - hooks/ - utils/ +- **遵循以下文件夹结构**： + - **`src/`**：项目源代码根目录。 + - **`components/`**：存放可复用的 UI 组件。 + - **`common/`**：通用组件，如按钮、输入框等。 + - **`layout/`**：布局相关组件，如 Header, Footer, Sidebar 等。 + - **`specific/`**：特定业务或页面使用的组件。 + - **`pages/`**：存放页面组件，每个文件代表一个路由页面。 + - **`theme/`**：存放 Chakra UI 主题相关的配置。 + - **`index.js`**：主题的入口文件，用于组合所有主题配置。 + - **`foundations/`**：基础样式，如颜色、字体、间距、断点等。 + - **`components/`**：组件样式覆盖和变体。 + - **`hooks/`**：存放自定义 React Hooks。 + - **`utils/`**：存放工具函数、常量、辅助函数等。 + - **`assets/`**：存放静态资源，如图片、字体、SVG 等。 + - **`App.js`**：应用程序的根组件。 + - **`index.js`**：应用程序的入口文件，通常用于渲染 `App` 组件并包裹 `ChakraProvider`。 + - **优点**： + - **清晰的职责分离**：每个目录都有明确的用途，便于团队协作和新成员快速上手。 + - **可维护性**：逻辑和 UI 分离，便于修改和扩展。 + - **可扩展性**：随着项目增长，可以轻松添加新的模块和功能。 + - **一致性**：统一的结构有助于保持整个代码库的一致性。 diff --git a/rules/frontend/react/chakra-ui/react-chakra-ui---general-preferences.mdc b/rules/frontend/react/chakra-ui/react-chakra-ui---general-preferences.mdc index db6e0d0..57944b5 100644 --- a/rules/frontend/react/chakra-ui/react-chakra-ui---general-preferences.mdc +++ b/rules/frontend/react/chakra-ui/react-chakra-ui---general-preferences.mdc @@ -1,5 +1,40 @@ --- -description: 使用 Chakra UI 的 React 组件的一般偏好，包括使用带有 hooks 的函数式组件。 +description: "使用 Chakra UI 的 React 组件的一般偏好，包括使用带有 hooks 的函数式组件" globs: src/**/*.* --- -- 优先使用带有 hooks 的函数式组件 +- **优先使用带有 hooks 的函数式组件**： + - **现代化开发**：在 Chakra UI 项目中，优先使用 React 函数式组件和 Hooks 进行开发，而不是类组件。 + - **代码简洁性**：Hooks 使得组件逻辑更易于组织和测试，减少了冗余代码。 + - **逻辑复用**：自定义 Hooks 可以轻松地在不同组件之间共享状态逻辑。 + - **性能优化**：结合 `React.memo`、`useCallback` 和 `useMemo` 可以更好地控制组件的渲染行为，优化性能。 + - **示例**： + ```jsx + import { Box, Button, useToast } from '@chakra-ui/react'; + import React, { useState, useCallback } from 'react'; + + function MyFunctionalComponent() { + const [count, setCount] = useState(0); + const toast = useToast(); + + const handleClick = useCallback(() => { + setCount(prevCount => prevCount + 1); + toast({ + title: 'Count updated.', + description: `Count is now ${count + 1}`, + status: 'success', + duration: 1000, + isClosable: true, + }); + }, [count, toast]); + + return ( + + Count: {count} + + + ); + } + ``` + - **与 Chakra UI 的兼容性**：Chakra UI 的 Hooks（如 `useColorMode`, `useDisclosure`）与函数式组件无缝集成，提供了强大的功能扩展。 diff --git a/rules/frontend/react/chakra-ui/react-chakra-ui---typescript-usage.mdc b/rules/frontend/react/chakra-ui/react-chakra-ui---typescript-usage.mdc index 9207ea9..2bb6bc4 100644 --- a/rules/frontend/react/chakra-ui/react-chakra-ui---typescript-usage.mdc +++ b/rules/frontend/react/chakra-ui/react-chakra-ui---typescript-usage.mdc @@ -1,5 +1,31 @@ --- -description: 在使用 Chakra UI 的 React 组件时利用 TypeScript 确保类型安全。 +description: "在使用 Chakra UI 的 React 组件时利用 TypeScript 确保类型安全" globs: src/**/*.tsx --- -- 对 Chakra UI 组件使用 TypeScript 确保类型安全 +- **对 Chakra UI 组件使用 TypeScript 确保类型安全**： + - **类型推断**：Chakra UI 组件通常具有良好的 TypeScript 类型定义，可以自动推断 props 的类型，减少手动定义的工作量。 + - **自定义组件的类型定义**： + - 当创建自定义组件并包裹 Chakra UI 组件时，应正确定义组件的 props 接口，并利用 Chakra UI 提供的类型工具（如 `ThemingProps`、`SystemProps`）来确保类型安全和智能提示。 + - 示例： + ```typescript + import { Box, BoxProps } from '@chakra-ui/react'; + import React from 'react'; + + interface CustomCardProps extends BoxProps { + title: string; + description: string; + } + + const CustomCard: React.FC = ({ title, description, children, ...rest }) => { + return ( + + {title} + {description} + {children} + + ); + }; + ``` + - **主题类型**：如果对 Chakra UI 主题进行了扩展，确保为自定义主题添加类型定义，以便在整个应用中获得类型安全。 + - **避免 `any` 类型**：尽量避免使用 `any` 类型，尤其是在处理 Chakra UI 组件的 props 或样式时，以充分利用 TypeScript 的优势。 + - **工具支持**：利用 VS Code 等 IDE 的 TypeScript 支持，获得代码补全、错误检查和重构等功能，提高开发效率。 diff --git a/rules/frontend/react/mobx/folder-structure.mdc b/rules/frontend/react/mobx/folder-structure.mdc index de4b137..be65ce2 100644 --- a/rules/frontend/react/mobx/folder-structure.mdc +++ b/rules/frontend/react/mobx/folder-structure.mdc @@ -1,11 +1,25 @@ --- -description: 为 React 和 MobX 项目强制执行特定的目录结构。 +description: "为 React 和 MobX 项目强制执行特定的目录结构" globs: src/** --- -- 维护以下文件夹结构： - src/ - components/ - stores/ - hooks/ - pages/ - utils/ +- **维护以下文件夹结构**： + - **`src/`**：项目源代码根目录。 + - **`components/`**：存放可复用的 React UI 组件。 + - **`common/`**：通用组件。 + - **`layout/`**：布局相关组件。 + - **`specific/`**：特定业务组件。 + - **`stores/`**：存放 MobX 状态管理相关的 store 文件。 + - **`rootStore.js`**：根 store，聚合所有子 store。 + - **`userStore.js`**：用户相关的 store。 + - **`itemStore.js`**：业务数据相关的 store。 + - **`hooks/`**：存放自定义 React Hooks，用于封装可复用的逻辑。 + - **`pages/`**：存放页面组件，每个文件代表一个路由页面。 + - **`utils/`**：存放工具函数、常量、辅助函数等。 + - **`assets/`**：存放静态资源，如图片、字体、SVG 等。 + - **`App.js`**：应用程序的根组件。 + - **`index.js`**：应用程序的入口文件，通常用于渲染 `App` 组件并设置 MobX Provider。 + - **优点**： + - **清晰的职责分离**：每个目录都有明确的用途，便于团队协作和新成员快速上手。 + - **可维护性**：逻辑和 UI 分离，便于修改和扩展。 + - **可扩展性**：随着项目增长，可以轻松添加新的模块和功能。 + - **一致性**：统一的结构有助于保持整个代码库的一致性。 diff --git a/rules/frontend/react/mobx/mobx-best-practices.mdc b/rules/frontend/react/mobx/mobx-best-practices.mdc index 0d96dbf..1739303 100644 --- a/rules/frontend/react/mobx/mobx-best-practices.mdc +++ b/rules/frontend/react/mobx/mobx-best-practices.mdc @@ -1,5 +1,15 @@ --- -description: 遵循 MobX 最佳实践以实现可扩展的状态管理。 +description: "遵循 MobX 最佳实践以实现可扩展的状态管理" globs: src/**/*.ts --- -- 遵循 MobX 可扩展状态管理的最佳实践。 +- **遵循 MobX 可扩展状态管理的最佳实践**： + - **明确可观察状态**：使用 `@observable` 或 `makeObservable` 明确定义哪些属性是可观察的，避免不必要的响应。 + - **使用计算值（`@computed`）**：对于从可观察状态派生出的值，使用 `@computed`。它们只在依赖项改变时重新计算，提高性能。 + - **使用动作（`@action`）修改状态**：所有状态修改都应通过 `@action` 标记的函数进行，这有助于调试和确保状态更新的原子性。 + - **避免在渲染中修改状态**：不要在 React 组件的 `render` 方法或函数组件的顶层直接修改 MobX 状态，这可能导致无限循环或不可预测的行为。 + - **细粒度可观察性**：尽量使可观察状态的粒度更细，例如，将一个大对象分解为多个小对象，这样只有当特定部分改变时才会触发更新。 + - **使用 `reaction` 或 `autorun` 进行副作用处理**：对于需要响应状态变化并执行副作用（如日志记录、网络请求）的场景，使用 `reaction` 或 `autorun`，而不是在组件中直接处理。 + - **依赖注入**：使用 React Context 或其他依赖注入模式来提供 MobX store，避免 prop drilling。 + - **严格模式（`useStrict`）**：在开发模式下启用严格模式，强制所有状态修改都通过 action 进行，有助于早期发现问题。 + - **测试**：为 MobX store 编写单元测试，确保状态逻辑的正确性。 + - **避免过度使用 MobX**：对于简单的组件内部状态，可以考虑使用 React 的 `useState` 和 `useReducer`，而不是总是引入 MobX。 diff --git a/rules/frontend/react/mobx/mobx-dependency-injection.mdc b/rules/frontend/react/mobx/mobx-dependency-injection.mdc index a1c3fe5..82a8fba 100644 --- a/rules/frontend/react/mobx/mobx-dependency-injection.mdc +++ b/rules/frontend/react/mobx/mobx-dependency-injection.mdc @@ -1,5 +1,52 @@ --- -description: 为 stores 实现适当的依赖注入。 +description: "为 stores 实现适当的依赖注入" globs: src/**/*.ts --- -- 为 stores 实现适当的依赖注入。 +- **为 stores 实现适当的依赖注入**： + - **使用 React Context 提供 store**： + - 推荐使用 React Context API 来将 MobX store 注入到组件树中，避免手动通过 props 层层传递（prop drilling）。 + - 创建一个 `StoreContext`，并在应用程序的根组件中使用 `Provider` 提供 store 实例。 + - 示例： + ```jsx + // stores/index.js + import { createContext, useContext } from 'react'; + import { RootStore } from './RootStore'; + + export const RootStoreInstance = new RootStore(); + export const StoreContext = createContext(RootStoreInstance); + export const useStore = () => useContext(StoreContext); + + // App.js + import React from 'react'; + import { StoreContext, RootStoreInstance } from './stores'; + + function App() { + return ( + + {/* Your application components */} + + ); + } + ``` + - **自定义 Hook 简化使用**： + - 创建一个自定义 Hook（如 `useStore`）来简化组件中对 store 的访问，提高代码可读性。 + - 示例： + ```jsx + // components/MyComponent.js + import React from 'react'; + import { observer } from 'mobx-react-lite'; + import { useStore } from '../stores'; + + const MyComponent = observer(() => { + const { userStore } = useStore(); + + return ( +
+

User Name: {userStore.name}

+ +
+ ); + }); + ``` + - **测试友好**：依赖注入使得在单元测试中替换或模拟 store 变得容易，提高了测试的独立性和效率。 + - **避免全局变量**：避免将 store 实例作为全局变量直接导入，这会降低模块的独立性和可测试性。 diff --git a/rules/frontend/react/mobx/mobx-devtools.mdc b/rules/frontend/react/mobx/mobx-devtools.mdc index 254c6f1..53e5889 100644 --- a/rules/frontend/react/mobx/mobx-devtools.mdc +++ b/rules/frontend/react/mobx/mobx-devtools.mdc @@ -1,5 +1,46 @@ --- -description: 利用 MobX DevTools 调试 MobX 应用程序。 +description: "利用 MobX DevTools 调试 MobX 应用程序" globs: src/**/*.ts --- -- 利用 MobX DevTools 进行调试。 +- **利用 MobX DevTools 调试 MobX 应用程序**： + - **安装**： + - 对于 Chrome 或 Firefox 浏览器，安装 MobX DevTools 扩展。 + - 在项目中安装 `mobx-react-devtools` 包（通常仅在开发环境使用）： + ```bash + npm install --save-dev mobx-react-devtools + # 或者 + yarn add --dev mobx-react-devtools + ``` + - **集成**： + - 在应用程序的入口文件（如 `index.js` 或 `App.js`）中导入并渲染 `DevTools` 组件。 + - 示例： + ```jsx + import React from 'react'; + import ReactDOM from 'react-dom/client'; + import App from './App'; + + // 仅在开发环境导入 DevTools + if (process.env.NODE_ENV === 'development') { + const DevTools = require('mobx-react-devtools').default; + ReactDOM.createRoot(document.getElementById('root')).render( + + + + + ); + } else { + ReactDOM.createRoot(document.getElementById('root')).render( + + + + ); + } + ``` + - **功能**： + - **状态检查**：实时查看 MobX store 的状态，包括可观察数据、计算值和 action。 + - **时间旅行调试**：回溯和重放状态变化，帮助理解数据流和定位问题。 + - **Action 追踪**：记录所有 action 的执行，显示其参数和对状态的影响。 + - **性能分析**：识别哪些组件因为哪些状态变化而重新渲染，优化性能。 + - **最佳实践**： + - 仅在开发环境中使用 MobX DevTools，避免在生产环境中打包。 + - 结合浏览器开发者工具一起使用，更全面地调试应用程序。 diff --git a/rules/frontend/react/mobx/mobx-react-lite-usage.mdc b/rules/frontend/react/mobx/mobx-react-lite-usage.mdc index 9be49f4..3ba00b2 100644 --- a/rules/frontend/react/mobx/mobx-react-lite-usage.mdc +++ b/rules/frontend/react/mobx/mobx-react-lite-usage.mdc @@ -1,5 +1,53 @@ --- -description: 在使用 MobX 与 React Lite 时强制执行最佳实践。 +description: "在使用 MobX 与 React Lite 时强制执行最佳实践" globs: src/components/**/*.tsx --- -- 使用 MobX-react-lite 以在函数式组件中获得最佳性能。 +- **使用 MobX-react-lite 以在函数式组件中获得最佳性能**： + - **`observer` HOC 或 `useObserver` Hook**： + - 对于函数式组件，推荐使用 `mobx-react-lite` 提供的 `observer` 高阶组件（HOC）或 `useObserver` Hook 来包裹组件，使其能够响应 MobX 状态的变化。 + - `observer` HOC 示例： + ```jsx + import React from 'react'; + import { observer } from 'mobx-react-lite'; + import { useStore } from '../stores'; + + const TodoList = observer(() => { + const { todoStore } = useStore(); + + return ( +
+ {todoStore.todos.map(todo => ( +
{todo.text}
+ ))} +
+ ); + }); + + export default TodoList; + ``` + - `useObserver` Hook 示例（适用于需要更细粒度控制渲染的场景）： + ```jsx + import React from 'react'; + import { useObserver } from 'mobx-react-lite'; + import { useStore } from '../stores'; + + const TodoItem = ({ todo }) => { + return useObserver(() => ( +
  • + {todo.text} + +
    • + )); + }; + + export default TodoItem; + ``` + - **性能优化**： + - `mobx-react-lite` 针对函数式组件进行了优化，只在组件实际观察到的数据发生变化时才重新渲染组件，从而最大限度地减少不必要的渲染。 + - 避免在 `observer` 组件内部解构 MobX store 的可观察属性，这可能导致组件观察到整个 store 而不是特定属性，从而触发不必要的重新渲染。应在组件内部访问具体属性。 + - **与 Hooks 结合使用**： + - `mobx-react-lite` 与 React Hooks 完美结合，可以在 `observer` 组件内部自由使用 `useState`, `useEffect`, `useContext` 等 Hooks。 + - **轻量级**： + - `mobx-react-lite` 是一个轻量级的包，只提供了 MobX 与 React 函数式组件集成的核心功能，没有额外的负担。 diff --git a/rules/frontend/react/mobx/mobx-reaction-usage.mdc b/rules/frontend/react/mobx/mobx-reaction-usage.mdc index e6db5e3..1750827 100644 --- a/rules/frontend/react/mobx/mobx-reaction-usage.mdc +++ b/rules/frontend/react/mobx/mobx-reaction-usage.mdc @@ -1,5 +1,56 @@ --- -description: 使用 reaction 处理基于可观察变化的副作用。 +description: "使用 reaction 处理基于可观察变化的副作用" globs: src/**/*.ts --- -- 使用 reaction 处理基于可观察变化的副作用。 +- **使用 `reaction` 处理基于可观察变化的副作用**： + - **`reaction` 的作用**： + - `reaction` 是 MobX 提供的一种副作用处理机制，它接受两个函数作为参数：第一个函数（`data` 函数）跟踪其内部使用的可观察数据，并返回一个值；第二个函数（`effect` 函数）接收 `data` 函数的返回值，并在 `data` 函数返回的值发生变化时执行。 + - 与 `autorun` 不同，`reaction` 允许你更精确地控制哪些数据变化会触发副作用，并且 `effect` 函数不会在初始化时立即运行。 + - **使用场景**： + - 当你需要根据 MobX 状态的变化执行一些副作用，例如： + - 异步数据加载（例如，当用户 ID 变化时加载用户数据）。 + - 订阅外部服务或事件。 + - 写入本地存储（localStorage）。 + - 打印日志。 + - **示例**： + ```typescript + import { makeObservable, observable, action, reaction } from 'mobx'; + + class UserStore { + @observable userId = 0; + @observable userData = null; + + constructor() { + makeObservable(this); + reaction( + () => this.userId, // data 函数：跟踪 userId + async (userId) => { + if (userId > 0) { + console.log(`Fetching user data for userId: ${userId}`); + // 模拟异步请求 + this.userData = await new Promise(resolve => + setTimeout(() => resolve({ id: userId, name: `User ${userId}` }), 500) + ); + } else { + this.userData = null; + } + }, + { fireImmediately: true } // 立即执行一次 effect 函数 + ); + } + + @action + setUserId(id: number) { + this.userId = id; + } + } + + const userStore = new UserStore(); + userStore.setUserId(1); // 这将触发 reaction，加载用户数据 + // userStore.setUserId(2); // 再次触发 reaction + ``` + - **最佳实践**： + - 尽量在 store 内部使用 `reaction` 来处理与状态相关的副作用，保持组件的纯粹性。 + - 避免在 `data` 函数中执行耗时操作，因为它会频繁运行。 + - 如果副作用需要清理（例如，取消订阅），`reaction` 函数会返回一个清理函数，可以在组件卸载时调用它。 + - 对于简单的、不依赖于特定数据变化的副作用，可以考虑使用 `autorun`。 diff --git a/rules/frontend/react/nextjs-basic/README.md b/rules/frontend/react/nextjs-basic/README.md index e14cc56..4a433f1 100644 --- a/rules/frontend/react/nextjs-basic/README.md +++ b/rules/frontend/react/nextjs-basic/README.md @@ -6,6 +6,24 @@ 学习用交互式编码助手：使用指定技术栈的 Web 应用程序，为新开发人员提供交互式编码课程和练习，集成 LLM 进行实时反馈、解释和 TypeScript 逐步指导。它可以允许用户在浏览器中编写代码、接收反馈并查看实际示例。AI 驱动的代码审查工具：开发一个在线平台，开发人员可以提交代码进行 AI 辅助审查，使用 LLM。该工具将分析代码库，提供改进建议，检测潜在错误，并遵循最佳实践，从而提高代码质量和性能。自动化文档生成器：创建一个利用 LLM 从用 TypeScript 编写的代码库自动生成全面清晰文档的服务，解释每个函数的目的、参数和典型用例。AI 驱动的错误修复服务：一个开发人员可以提交带有错误的代码片段的平台，LLM 将分析并建议修复。与所述前端和后端的集成将确保平稳运行，直接向 TypeScript 代码建议更改。协作编码环境：使用 Next.js 构建实时协作编码平台，允许多个用户编辑同一代码库，通过 LLM 集成提供实时反馈和建议，类似于编码的 Google Docs。个性化学习路径生成器：一个根据开发人员当前技能水平和期望目标提供自定义学习路径的应用程序。它使用 LLM 定制课程内容，并在 TypeScript 中提供练习，通过 Next.js 中的交互式示例并行。代码优化 AI 聊天机器人：开发一个使用集成到 Web 应用中的 LLM 的聊天机器人，开发人员可以粘贴代码片段以获得优化技巧和重构建议，以提高效率和性能。AI 驱动的 UI/UX 改进顾问：一个接受现有 Next.js 项目并使用 LLM 建议 UI/UX 改进的服务，利用 Tailwind CSS 进行设计增强，使用 Lucide React 改善图标美学。定制教程创建器：一个根据代码库输入自动创建教程的工具，使用 LLM 为 Next.js 和 TypeScript 中的特定编程任务或应用功能形成可读的逐步指南。智能代码库搜索引擎：专门为代码库实现搜索引擎，允许开发人员用自然语言输入查询来定位相关代码段。它使用 LLM 理解查询的意图和上下文，提供准确结果。 +## 技术栈要求 + +- **核心框架**: Next.js 14+(App Router模式) +- **语言**: TypeScript 5.0+ +- **样式**: Tailwind CSS + CSS Modules +- **UI组件**: shadcn/ui + Radix Primitives +- **图标库**: Lucide React +- **状态管理**: React Context + useReducer +- **API交互**: tRPC + Zod验证 + +## 编码规范 + +1. **文件组织**: 遵循Next.js官方项目结构 +2. **类型定义**: 所有props和API响应必须定义TS接口 +3. **样式隔离**: 组件级CSS Modules +4. **性能优化**: 自动代码分割+动态导入 +5. **安全实践**: 输入验证+CSRF防护 + ## 优势 diff --git a/rules/frontend/react/nextjs-basic/assistant-response-rules.mdc b/rules/frontend/react/nextjs-basic/assistant-response-rules.mdc index eccd0d6..38fa3c9 100644 --- a/rules/frontend/react/nextjs-basic/assistant-response-rules.mdc +++ b/rules/frontend/react/nextjs-basic/assistant-response-rules.mdc @@ -1,14 +1,24 @@ --- -description: 定义助手应如何响应，包括其作为高级配对程序员的角色和响应所需格式，适用于所有文件。 +description: "定义助手应如何响应，包括其作为高级配对程序员的角色和响应所需格式，适用于所有文件" globs: * --- -- 你是用户的高级、好奇且聪明的配对程序员。让我们逐步进行： -- 除非你只是回答一个快速问题，否则以以下内容开始你的响应： - """ +- **角色定位**：你是用户的高级、好奇且聪明的配对程序员。让我们逐步进行。 +- **响应格式**：除非你只是回答一个快速问题，否则以以下内容开始你的响应： + ``` 语言 > 专家：{使用的编程语言} > {主题专家专业角色} 包括：所需库、包和关键语言功能的 CSV 列表（如果有） 要求：详细程度、标准和软件设计要求的定性描述 计划 简要列出你的逐步计划，包括任何尚未处理的组件 - """ -- 像选定语言的专家专业人士一样行动并在遵循编码风格的同时响应。如果使用 Jupyter，现在开始。记住在顶部添加路径/文件名注释。 + ``` +- **行为准则**：像选定语言的专家专业人士一样行动，并遵循编码风格进行响应。如果使用 Jupyter，现在开始。记住在顶部添加路径/文件名注释。 +- **代码详细程度**： + - 如果是新文件，提供完整代码 + - 如果是现有文件修改，仅提供修改部分 +- **逐步推理**： + - 每次响应都应包含清晰的逐步推理 + - 解释为什么做出这些选择 +- **避免道歉**：不要为错误道歉，直接修复它们 +- **提问**： + - 如果对需求或技术栈有疑问，可以提问 + - 确保问题具体且有助于推进任务 diff --git a/rules/frontend/react/nextjs-basic/backend-stack-rules.mdc b/rules/frontend/react/nextjs-basic/backend-stack-rules.mdc index 6c71e76..e07ed48 100644 --- a/rules/frontend/react/nextjs-basic/backend-stack-rules.mdc +++ b/rules/frontend/react/nextjs-basic/backend-stack-rules.mdc @@ -1,6 +1,10 @@ --- -description: 指定后端技术栈，包括 Next.js API Routes 和 TypeScript，适用于所有后端文件。 +description: "指定后端技术栈，包括 Next.js API Routes 和 TypeScript，适用于所有后端文件" globs: backend/**/*.* --- -- 框架：Next.js API Routes（用于无服务器函数） -- 语言：TypeScript（用于 API 路由） +- **框架**：Next.js API Routes（用于无服务器函数） +- **语言**：TypeScript（用于 API 路由） +- **数据验证**：Zod（用于 API 请求和响应的数据验证） +- **ORM/数据库**：根据项目需求选择，例如 Prisma, Drizzle ORM 等 +- **认证**：NextAuth.js（如果需要用户认证） +- **部署**：Vercel（推荐用于Next.js应用） diff --git a/rules/frontend/react/nextjs-basic/coding-process-rules.mdc b/rules/frontend/react/nextjs-basic/coding-process-rules.mdc index 01edee8..f587a62 100644 --- a/rules/frontend/react/nextjs-basic/coding-process-rules.mdc +++ b/rules/frontend/react/nextjs-basic/coding-process-rules.mdc @@ -1,9 +1,9 @@ --- -description: 指定编码过程，包括逐步推理、优先级排序、在继续下一个文件之前完成一个文件，以及使用 TODO 注释，适用于所有文件。 +description: "指定编码过程，包括逐步推理、优先级排序、在继续下一个文件之前完成一个文件，以及使用 TODO 注释，适用于所有文件" globs: * --- -- 显示简洁的逐步推理 -- 优先考虑你将在每个响应中处理的任务/步骤 -- 在处理下一个文件之前完成一个文件 -- 如果无法完成代码，添加 TODO: 注释 -- 如果需要，中断自己并要求继续 +- **逐步推理**：显示简洁的逐步推理，解释决策过程。 +- **任务优先级**：优先考虑你将在每个响应中处理的任务/步骤，确保高效推进。 +- **文件完成度**：在处理下一个文件之前，务必完成当前文件的代码编写和相关修改。 +- **TODO注释**：如果无法完成代码或需要后续处理，请添加 `TODO:` 注释，明确待办事项。 +- **中断与继续**：如果需要用户介入或无法独立继续，可以中断并请求用户提供进一步指示。 diff --git a/rules/frontend/react/nextjs-basic/coding-style-rules.mdc b/rules/frontend/react/nextjs-basic/coding-style-rules.mdc index f865946..b7423f9 100644 --- a/rules/frontend/react/nextjs-basic/coding-style-rules.mdc +++ b/rules/frontend/react/nextjs-basic/coding-style-rules.mdc @@ -1,7 +1,24 @@ --- -description: 定义编码风格指导原则，包括注释、模块化、DRY 原则、性能和安全性，适用于所有文件。 +description: "Next.js项目编码风格规范，涵盖注释规范、模块化设计、DRY原则、性能与安全最佳实践" globs: * --- -- 代码必须以路径/文件名作为单行注释开始 -- 注释必须主要描述目的，但在必要时也要描述效果 -- 优先考虑模块化、DRY、性能和安全性 +- **文件头注释**: 必须包含文件路径和主要功能说明 + ```typescript + // src/components/ui/button.tsx + // 通用按钮组件，支持多种变体和尺寸 + ``` +- **代码注释**: + - 复杂逻辑必须添加行内注释 + - 避免无意义的注释（如"增加计数器"） +- **模块化**: + - 单一组件不超过300行 + - 每个组件/钩子只做一件事 +- **DRY原则**: + - 重复逻辑抽象为自定义钩子 + - 通用UI提取为共享组件 +- **性能**: + - 避免不必要的re-render + - 大数据列表使用虚拟滚动 +- **安全**: + - 所有用户输入必须验证 + - 敏感操作需要二次确认 diff --git a/rules/frontend/react/nextjs-basic/editing-code-rules.mdc b/rules/frontend/react/nextjs-basic/editing-code-rules.mdc index e2e7adc..fe2f384 100644 --- a/rules/frontend/react/nextjs-basic/editing-code-rules.mdc +++ b/rules/frontend/react/nextjs-basic/editing-code-rules.mdc @@ -1,5 +1,9 @@ --- -description: 优先返回完全编辑的文件并定义代码详细程度级别，适用于所有文件。 +description: "优先返回完全编辑的文件并定义代码详细程度级别，适用于所有文件" globs: * --- -- 返回完全编辑的文件 +- **返回完全编辑的文件**：每次代码修改后，应返回完整且经过编辑的文件内容，确保代码的完整性和可读性。 +- **代码详细程度**： + - 对于新创建的文件，提供完整的代码实现。 + - 对于现有文件的修改，仅提供修改部分的代码，并清晰标示出修改前后的差异，以便用户快速理解。 +- **确保可运行性**：所有返回的代码片段都必须是可运行的，并且包含所有必要的依赖项和配置，以确保用户可以直接使用。 diff --git a/rules/frontend/react/nextjs-basic/frontend-stack-rules.mdc b/rules/frontend/react/nextjs-basic/frontend-stack-rules.mdc index 257b2a1..5ea6ec2 100644 --- a/rules/frontend/react/nextjs-basic/frontend-stack-rules.mdc +++ b/rules/frontend/react/nextjs-basic/frontend-stack-rules.mdc @@ -1,9 +1,12 @@ --- -description: 指定前端技术栈，包括 React、TypeScript、Shadcn/UI、Tailwind CSS 和 Lucide React，适用于所有前端文件。 +description: "指定前端技术栈，包括 React、TypeScript、Shadcn/UI、Tailwind CSS 和 Lucide React，适用于所有前端文件" globs: frontend/**/*.* --- -- 框架：Next.js (React) -- 语言：TypeScript -- UI 组件：shadcn/ui（基于 Radix UI 原语） -- 样式：Tailwind CSS -- 图标：Lucide React +- **核心框架**：Next.js (基于 React) +- **语言**：TypeScript +- **UI 组件库**：shadcn/ui（基于 Radix UI 原语构建，提供可定制的UI组件） +- **样式框架**：Tailwind CSS（实用优先的CSS框架，用于快速构建自定义设计） +- **图标库**：Lucide React（一套美观且高度可定制的开源图标库） +- **状态管理**：React Context API 和 useReducer Hook（用于应用级状态管理） +- **数据获取**：React Query 或 SWR（用于优化数据获取、缓存和同步） +- **表单管理**：React Hook Form 和 Zod（用于表单状态管理和数据验证） diff --git a/rules/frontend/react/nextjs-basic/general-assistant-rules.mdc b/rules/frontend/react/nextjs-basic/general-assistant-rules.mdc index 2ea324e..c251bb6 100644 --- a/rules/frontend/react/nextjs-basic/general-assistant-rules.mdc +++ b/rules/frontend/react/nextjs-basic/general-assistant-rules.mdc @@ -1,7 +1,11 @@ --- -description: 为所有文件定义一般助手行为，包括如何处理错误、提问和理解项目技术栈。 +description: "为所有文件定义一般助手行为，包括如何处理错误、提问和理解项目技术栈" globs: * --- -- 对需求和技术栈的整体理解 -- 不要为错误道歉：修复它们 -- 如果编写代码，你可以询问技术栈假设 +- **全面理解**：对用户需求和项目技术栈有全面深入的理解。 +- **错误处理**：不要为错误道歉，而是直接着手修复它们，并解释修复过程。 +- **主动提问**： + - 在编写代码时，如果对技术栈的某些假设不确定，可以主动向用户提问以澄清。 + - 提问应具体且有助于推进任务，避免模糊或不必要的问题。 +- **提供解决方案**：除了修复问题，还应提供优化建议或更好的实现方案。 +- **保持一致性**：在所有交互和代码输出中，保持行为和风格的一致性。 diff --git a/rules/frontend/react/nextjs-basic/history-and-next-task-rules.mdc b/rules/frontend/react/nextjs-basic/history-and-next-task-rules.mdc index b997536..f2086d0 100644 --- a/rules/frontend/react/nextjs-basic/history-and-next-task-rules.mdc +++ b/rules/frontend/react/nextjs-basic/history-and-next-task-rules.mdc @@ -1,13 +1,16 @@ --- -description: 指定结束响应的格式，包括需求摘要、编写的代码、源代码树和下一个任务，适用于所有文件。 +description: "指定结束响应的格式，包括需求摘要、编写的代码、源代码树和下一个任务，适用于所有文件" globs: * --- -- 考虑整个聊天会话，并按以下方式结束你的响应： - """ +- **响应结束格式**：考虑整个聊天会话，并按以下方式结束你的响应： + ``` 历史：所有需求和你编写的所有代码的完整、简洁和压缩摘要 源代码树：（示例，替换表情符号） (:floppy_disk:=已保存：文件链接，:warning:=未保存但已命名的片段，:ghost:=无文件名）file.ext:package: Class（如果存在） (:white_check_mark:=已完成，:o:=有 TODO，:red_circle:=其他未完成）symbol:red_circle: 全局符号 等等。 下一个任务：未完成=下一个任务的简短描述 已完成=列出专家专业人士对增强/性能改进的建议。 - """ + ``` +- **历史记录**：确保历史记录清晰、简洁，涵盖所有已完成的需求和代码。 +- **源代码树**：提供直观的源代码树表示，帮助用户快速了解文件状态。 +- **下一个任务**：明确指出下一步计划，保持任务的连续性和透明度。 diff --git a/rules/frontend/react/nextjs-basic/llm-integration-rules.mdc b/rules/frontend/react/nextjs-basic/llm-integration-rules.mdc index 35dc404..3ff7224 100644 --- a/rules/frontend/react/nextjs-basic/llm-integration-rules.mdc +++ b/rules/frontend/react/nextjs-basic/llm-integration-rules.mdc @@ -1,6 +1,10 @@ --- -description: 指定 LLM 集成规则，包括使用 Python 包装器和 API 端点，适用于所有 LLM 相关文件。 +description: "指定 LLM 集成规则，包括使用 Python 包装器和 API 端点，适用于所有 LLM 相关文件" globs: llm/**/*.* --- -- 用于 LLM 交互的 Python 包装器 -- 连接前端与 Python 后端的 API 端点 +- **Python 包装器**：使用专门的 Python 包装器进行 LLM 交互，确保接口统一和易于管理。 +- **API 端点**：通过清晰定义的 API 端点连接前端与 Python 后端，实现前后端数据传输和功能调用。 +- **异步处理**：LLM 调用通常耗时较长，应采用异步处理机制，避免阻塞主线程。 +- **错误处理与重试**：实现健壮的错误处理和重试机制，应对 LLM 服务可能出现的临时故障。 +- **安全性**：确保 LLM 交互过程中的数据安全，例如敏感信息加密、API 密钥管理等。 +- **性能优化**：对 LLM 请求和响应进行优化，例如批量请求、数据压缩等，提升整体性能。 From 0b216ad91ff04ff9191df8d0b3f93070ff3f6b22 Mon Sep 17 00:00:00 2001 From: None Date: Wed, 2 Jul 2025 15:01:43 +0800 Subject: [PATCH 03/19] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0MobX=E7=9B=B8?= =?UTF-8?q?=E5=85=B3=E8=A7=84=E5=88=99=E6=96=87=E6=A1=A3=E5=8F=8A=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 56 +++++---- README.md | 15 +++ docs/roadmap.md | 14 +++ docs/translation-progress.md | 46 ++++++++ docs/troubleshooting.md | 30 +++++ .../react/mobx/mobx-store-implementation.mdc | 106 +++++++++++++++++- .../frontend/react/mobx/mobx-strict-mode.mdc | 31 ++++- .../mobx/observer-hoc-or-useobserver-hook.mdc | 59 +++++++++- .../react/mobx/react-general-preferences.mdc | 42 ++++++- .../react/mobx/typescript-with-mobx.mdc | 74 +++++++++++- rules/frontend/react/nextjs-14-seo/README.md | 10 +- 11 files changed, 445 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3591c31..5b2adc5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， 并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 +## [1.2.0] - 2025-07-02 + +### 文档更新 +- 重构翻译进度报告结构，添加详细领域统计 +- 更新项目路线图至2025下半年 +- 新增翻译问题排查指南 +- 完善术语一致性检查流程 + ## [1.1.0] - 2025-06-25 ### 新增 @@ -16,9 +24,9 @@ ## [1.0.1] - 2025-05-29 -### 🔧 项目管理优化 +### 项目管理优化 -#### ✨ AI辅助工具集重构 +#### AI辅助工具集重构 - **重构 ai-help 目录结构**: 将项目管理工具集重新组织为清晰的三层架构 - `docs/` - 项目管理文档 (PROJECT_STATUS.md, promotion-strategy.md, setup-guide.md) - `scripts/` - 自动化脚本 (批量翻译、状态检查、内容迁移工具) @@ -27,20 +35,20 @@ - **功能优化**: 删除冗余脚本，保留核心功能，提升工具集可维护性 - **文档更新**: 完善工具集说明文档，明确使用场景和最佳实践 -#### 📋 项目管理改进 +#### 项目管理改进 - **工作流程优化**: 建立清晰的翻译管理、状态跟踪、版本发布流程 - **工具集整合**: 统一项目管理工具，提升开发效率 - **文档体系**: 完善项目状态报告和推广策略文档 ## [1.0.0] - 2024-01-XX -### 🎉 首次发布 +### 首次发布 这是 Awesome Cursor Rules 中文版的首次正式发布！ -### ✨ 新增功能 +### 新增功能 -#### 📚 完整翻译的规则集 (29个) +#### 完整翻译的规则集 (29个) - **React 生态系统** (13个规则集) - Next.js + TypeScript 完整配置 - React 组件开发最佳实践 @@ -77,59 +85,59 @@ - **CMS 开发** (1个规则集) - Drupal 11 内容管理系统 -#### 🏗️ 项目结构 +#### 项目结构 - 按技术栈分类的清晰目录结构 - 前端/后端/区块链/系统编程分类 - 155+ 个翻译文件，覆盖主流技术栈 -#### 📖 完善文档 +#### 完善文档 - 中文 README 和项目介绍 - 详细的快速开始指南 - 贡献指南和翻译标准 - 项目路线图和发展规划 - 常见问题解答 -#### 🔧 开发工具 +#### 开发工具 - GitHub Actions 自动化质量检查 - Markdown 格式验证 - .cursorrules 文件格式检查 - 项目结构完整性验证 -#### 🤝 社区功能 +#### 社区功能 - GitHub Issue 模板 (Bug 报告、功能请求、翻译请求) - Pull Request 模板 - 贡献者指南 - 社区讨论支持 -### 📊 项目统计 +### 项目统计 - **总目录数**: 45+ - **翻译文件数**: 155+ - **技术栈覆盖**: 10+ 主流技术领域 - **文档页面**: 15+ -### 🎯 支持的技术栈 -- ✅ React / Next.js / React Native -- ✅ Vue 3 / Nuxt 3 -- ✅ TypeScript / JavaScript -- ✅ Node.js / Express / NestJS -- ✅ Python / FastAPI -- ✅ C++ / Solidity -- ✅ iOS / Android -- ✅ Tailwind CSS / Chakra UI / Styled Components - -### 🌟 特色功能 +### 支持的技术栈 +- React / Next.js / React Native +- Vue 3 / Nuxt 3 +- TypeScript / JavaScript +- Node.js / Express / NestJS +- Python / FastAPI +- C++ / Solidity +- iOS / Android +- Tailwind CSS / Chakra UI / Styled Components + +### 特色功能 - **中文优化**: 所有内容针对中文开发者优化 - **技术栈分类**: 清晰的目录结构便于查找 - **质量保证**: 自动化检查确保翻译质量 - **社区驱动**: 完善的贡献流程和社区支持 -### 📝 使用方法 +### 使用方法 1. 克隆仓库到本地 2. 选择适合的技术栈规则集 3. 复制 .cursorrules 文件到项目根目录 4. 在 Cursor AI 中开始编程 -### 🙏 致谢 +### 致谢 感谢 [awesome-cursorrules](https://github.com/PatrickJS/awesome-cursorrules) 原项目的启发和所有贡献者的努力！ --- diff --git a/README.md b/README.md index 5b0574a..96ac02c 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,21 @@ 我们诚挚邀请您查看我们的 [**项目待办清单 (PROJECT_TODO.md)**](./PROJECT_TODO.md)，在这里您可以了解到我们接下来的翻译目标，并选择您感兴趣的任务参与贡献！ +## 📊 最新进展（2025年7月） +- **翻译进度**：已完成34份规则文件（34%） +- **重点完成**： + - React/Next.js核心规则 + - Kubernetes文档规范 + - GitHub代码质量指南 +- **查看详细进度**：[翻译进度报告](./docs/translation-progress.md) + +## 🚧 参与贡献 +我们急需以下领域的翻译专家： +1. **数据科学**：Python数据处理、机器学习 +2. **云原生**：服务网格、无服务器架构 +3. **移动开发**：React Native性能优化 +[查看贡献指南](./CONTRIBUTING.md) + ## 📊 翻译进度一览 我们正在根据优先级翻译原项目中的核心规则集。以下是当前主要任务的进度概览，欢迎您认领感兴趣的任务！ diff --git a/docs/roadmap.md b/docs/roadmap.md index 13497e0..f18e915 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -30,6 +30,20 @@ - [ ] 建立社区治理机制 - [ ] 国际化支持 +## 2025下半年路线图 + +### Q3目标（2025年7月-9月） +- **完成数据科学领域翻译**：包括Python数据处理、机器学习等核心规则 +- **云原生关键规范**：完成服务网格、无服务器架构和多云部署指南 +- **建立术语库**：统一技术术语翻译，提高一致性 +- **社区协作机制**：建立翻译审校流程，邀请专家参与 + +### Q4目标（2025年10月-12月） +- **移动开发完整指南**：覆盖React Native和跨平台开发 +- **区块链高级主题**：智能合约安全和DeFi模式 +- **自动化测试覆盖**：实现翻译文档的自动化校验 +- **多语言支持**：启动日文和韩文翻译计划 + ## 📊 翻译优先级 ### 🔥 高优先级 (4周内) diff --git a/docs/translation-progress.md b/docs/translation-progress.md index 8374eb4..7ec2afd 100644 --- a/docs/translation-progress.md +++ b/docs/translation-progress.md @@ -153,6 +153,38 @@ - 性能优化指南 - 安全开发规范 +## ⚠️ 未翻译重点部分 +1. **数据科学领域**： + - Python数据处理规则 + - 机器学习最佳实践 + - 数据可视化指南 + +2. **云原生开发**： + - 服务网格(Service Mesh)配置 + - 无服务器(Serverless)模式 + - 多云部署策略 + +3. **移动开发**： + - React Native性能优化 + - 跨平台开发规范 + - 移动端安全实践 + +## 🚀 后续翻译计划 +1. **优先级排序**： + ```mermaid + timeline + title 翻译计划时间线 + 2025-07-10 ： 完成数据科学核心规则 + 2025-07-20 ： 完成云原生关键规范 + 2025-07-31 ： 完成移动开发基础指南 + 2025-08-15 ： 完成所有高优先级规则 + ``` + +2. **质量保证措施**： + - 新增术语一致性检查 + - 引入社区评审机制 + - 建立翻译记忆库 + ## 🤝 贡献翻译 ### 如何参与 @@ -200,6 +232,20 @@ - **中优先级**: 15/35 (43% 完成) - **低优先级**: 6/70 (9% 完成) +## 📊 详细统计数据 +| 技术领域 | 已完成文件数 | 总文件数 | 完成率 | +|----------|--------------|----------|--------| +| 前端开发 | 18 | 30 | 60% | +| 后端开发 | 6 | 21 | 29% | +| 移动开发 | 2 | 10 | 20% | +| 区块链 | 1 | 4 | 25% | +| 数据科学 | 0 | 6 | 0% | +| 云原生 | 1 | 8 | 12% | +| 系统编程 | 1 | 5 | 20% | +| 通用工具 | 2 | 7 | 29% | +| DevOps | 3 | 10 | 30% | +| **总计** | **34** | **101** | **34%** | + ## 🎯 质量保证 ### 审核流程 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 41d8404..09f09e2 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -121,6 +121,36 @@ ls -lh .cursorrules - 避免过于复杂的规则 - 定期清理 Cursor 缓存 +### 6. 翻译问题 + +#### 技术术语不一致 +**问题描述**：相同术语在不同文件中有不同翻译 +**解决方案**： +1. 使用统一术语表（见`docs/terminology.md`） +2. 运行术语检查脚本：`python scripts/term_checker.py` +3. 接受自动修复建议或手动调整 + +#### 代码示例格式错误 +**问题描述**：翻译后代码缩进或格式破坏 +**解决方案**： +1. 使用Markdown代码块标识符指定语言类型 +2. 运行格式校验工具：`npm run lint:markdown` +3. 根据错误提示修正格式 + +#### 长句表达不清 +**问题描述**：英文长句直译导致中文晦涩 +**解决方案**： +1. 拆分长句为多个短句 +2. 调整语序符合中文习惯 +3. 保留技术准确性的前提下优化表达 +```markdown +# 不佳示例 +当组件被渲染时，状态更新将触发重新渲染 + +# 优化后 +组件渲染时，状态更新会触发重新渲染 +``` + ## 🔍 诊断工具 ### 1. 规则文件检查脚本 diff --git a/rules/frontend/react/mobx/mobx-store-implementation.mdc b/rules/frontend/react/mobx/mobx-store-implementation.mdc index 06b455b..fec8c60 100644 --- a/rules/frontend/react/mobx/mobx-store-implementation.mdc +++ b/rules/frontend/react/mobx/mobx-store-implementation.mdc @@ -1,8 +1,104 @@ --- -description: 实现 MobX stores 进行应用程序状态管理的指导原则。 +description: "实现 MobX stores 进行应用程序状态管理的指导原则" globs: src/stores/**/*.ts --- -- 实现 stores 来管理应用程序状态。 -- 利用计算值处理派生状态。 -- 使用 actions 修改可观察状态。 -- 在异步 actions 中实现适当的错误处理。 +- **实现 stores 来管理应用程序状态**： + - **定义可观察状态**： + - 使用 `@observable` 或 `makeObservable` 定义 store 中需要响应式跟踪的状态。 + - 示例： + ```typescript + import { makeObservable, observable, action, computed } from 'mobx'; + + class TodoStore { + @observable todos = []; + @observable isLoading = false; + @observable error = null; + + constructor() { + makeObservable(this); + } + + // ... actions and computed values + } + ``` + - **利用计算值（`@computed`）处理派生状态**： + - 对于可以从现有可观察状态派生出的数据，使用 `@computed` 属性。它们是惰性求值的，并且只有在依赖的可观察数据发生变化时才会重新计算。 + - 示例： + ```typescript + class TodoStore { + // ... + @computed + get completedTodosCount() { + return this.todos.filter(todo => todo.completed).length; + } + + @computed + get uncompletedTodos() { + return this.todos.filter(todo => !todo.completed); + } + } + ``` + - **使用动作（`@action`）修改可观察状态**： + - 所有修改 MobX store 可观察状态的函数都应该用 `@action` 标记。这有助于 MobX 批量更新，提高性能，并使调试更容易。 + - 示例： + ```typescript + class TodoStore { + // ... + @action + addTodo(text: string) { + this.todos.push({ id: Date.now(), text, completed: false }); + } + + @action + toggleTodo(id: number) { + const todo = this.todos.find(t => t.id === id); + if (todo) { + todo.completed = !todo.completed; + } + } + } + ``` + - **在异步 actions 中实现适当的错误处理**： + - 对于异步操作（如 API 调用），应在 action 中处理加载状态、成功和失败情况，并捕获错误。 + - 示例： + ```typescript + class TodoStore { + // ... + @action + async fetchTodos() { + this.isLoading = true; + this.error = null; + try { + // 模拟 API 调用 + const response = await new Promise(resolve => + setTimeout(() => resolve([{ id: 1, text: 'Learn MobX', completed: false }]), 1000) + ); + this.todos = response; + } catch (e) { + this.error = e; + } finally { + this.isLoading = false; + } + } + } + ``` + - **Store 的组合**： + - 对于大型应用，可以将多个相关的 store 组合成一个根 store，方便统一管理和访问。 + - 示例： + ```typescript + // RootStore.ts + import { makeObservable, observable } from 'mobx'; + import { TodoStore } from './TodoStore'; + import { UserStore } from './UserStore'; + + export class RootStore { + @observable todoStore: TodoStore; + @observable userStore: UserStore; + + constructor() { + makeObservable(this); + this.todoStore = new TodoStore(); + this.userStore = new UserStore(); + } + } + ``` diff --git a/rules/frontend/react/mobx/mobx-strict-mode.mdc b/rules/frontend/react/mobx/mobx-strict-mode.mdc index 81229f7..3d63228 100644 --- a/rules/frontend/react/mobx/mobx-strict-mode.mdc +++ b/rules/frontend/react/mobx/mobx-strict-mode.mdc @@ -1,5 +1,32 @@ --- -description: 为 MobX 强制执行严格模式以获得更好的调试体验。 +description: "为 MobX 强制执行严格模式以获得更好的调试体验" globs: src/stores/**/*.ts --- -- 为 MobX 实现严格模式以获得更好的调试体验。 +- **为 MobX 实现严格模式以获得更好的调试体验**： + - **什么是严格模式**： + - MobX 的严格模式（Strict Mode）是一种开发辅助功能，它强制所有状态修改都必须通过 `action` 进行。这意味着你不能在 `action` 之外直接修改任何可观察状态。 + - 启用严格模式有助于在开发阶段捕获意外的状态修改，从而避免难以调试的 bug。 + - **如何启用**： + - 在应用程序的入口文件或 MobX store 的初始化阶段，使用 `configure` 函数来启用严格模式。 + - 示例： + ```typescript + import { configure } from 'mobx'; + + // 仅在开发环境启用严格模式 + if (process.env.NODE_ENV === 'development') { + configure({ + enforceActions: 'always', + }); + } + ``` + - `enforceActions` 的可选值： + - `'never'` (默认)：允许在任何地方修改状态。 + - `'observed'`：只允许在 `action` 中修改被 MobX 观察到的状态。 + - `'always'`：强制所有状态修改都必须在 `action` 中进行，这是最严格的模式，推荐在开发环境使用。 + - **优点**： + - **早期错误检测**：在开发阶段就能发现并修复不规范的状态修改，避免潜在的运行时问题。 + - **清晰的数据流**：强制通过 `action` 修改状态，使得应用程序的数据流更加清晰和可预测。 + - **更好的调试体验**：当状态修改不符合规则时，MobX 会抛出错误，帮助开发者快速定位问题。 + - **注意事项**： + - 严格模式主要用于开发环境，不建议在生产环境中使用，因为它会增加一些运行时开销。 + - 确保所有状态修改都包裹在 `action` 中，包括异步操作中的状态更新。 diff --git a/rules/frontend/react/mobx/observer-hoc-or-useobserver-hook.mdc b/rules/frontend/react/mobx/observer-hoc-or-useobserver-hook.mdc index 76540fa..ac672bc 100644 --- a/rules/frontend/react/mobx/observer-hoc-or-useobserver-hook.mdc +++ b/rules/frontend/react/mobx/observer-hoc-or-useobserver-hook.mdc @@ -1,5 +1,60 @@ --- -description: 对响应式组件使用 Observer HOC 或 useObserver hook。 +description: "对响应式组件使用 Observer HOC 或 useObserver hook" globs: src/components/**/*.tsx --- -- 对响应式组件使用 observer HOC 或 useObserver hook。 +- **对响应式组件使用 `observer` HOC 或 `useObserver` hook**： + - **`observer` HOC（高阶组件）**： + - `observer` 是 `mobx-react-lite` 库提供的一个高阶组件，用于包裹 React 函数式组件或类组件，使其能够响应 MobX 状态的变化。 + - 当被包裹组件中使用的任何可观察数据发生变化时，`observer` 会触发组件的重新渲染。 + - 示例： + ```jsx + import React from 'react'; + import { observer } from 'mobx-react-lite'; + import { useStore } from '../stores'; + + const UserProfile = observer(() => { + const { userStore } = useStore(); + + return ( +
    +

    {userStore.name}

    +

    Email: {userStore.email}

    + +
    + ); + }); + + export default UserProfile; + ``` + - **`useObserver` Hook**： + - `useObserver` 是 `mobx-react-lite` 提供的另一个选择，它是一个 React Hook，允许你在函数式组件的内部定义一个响应式渲染块。 + - 它适用于需要更细粒度控制渲染，或者只希望组件的某个部分响应 MobX 状态变化的场景。 + - 示例： + ```jsx + import React from 'react'; + import { useObserver } from 'mobx-react-lite'; + import { useStore } from '../stores'; + + const ProductDisplay = ({ productId }) => { + const { productStore } = useStore(); + + return useObserver(() => { + const product = productStore.getProductById(productId); + if (!product) return
    Loading...
    ; + + return ( +
    +

    {product.name}

    +

    Price: ${product.price}

    +

    Stock: {product.stock}

    +
    + ); + }); + }; + + export default ProductDisplay; + ``` + - **选择建议**： + - **优先使用 `observer` HOC**：对于大多数情况，直接使用 `observer` HOC 包裹整个函数式组件是更简洁和推荐的做法。它会自动处理组件内部所有可观察数据的响应式更新。 + - **在特定场景使用 `useObserver` Hook**：当你需要在一个组件中，只有部分 UI 响应 MobX 状态变化，或者需要将响应式逻辑封装在自定义 Hook 中时，`useObserver` 提供了更大的灵活性。 + - **性能**：两者在性能上都非常高效，因为 `mobx-react-lite` 实现了精确的响应式更新，只在实际观察到的数据发生变化时才触发渲染。 diff --git a/rules/frontend/react/mobx/react-general-preferences.mdc b/rules/frontend/react/mobx/react-general-preferences.mdc index c1873f0..a076e8e 100644 --- a/rules/frontend/react/mobx/react-general-preferences.mdc +++ b/rules/frontend/react/mobx/react-general-preferences.mdc @@ -1,5 +1,43 @@ --- -description: 一般 React 偏好，优先使用带有 hooks 的函数式组件。 +description: "一般 React 偏好，优先使用带有 hooks 的函数式组件" globs: src/**/*.tsx --- -- 优先使用带有 hooks 的函数式组件。 +- **优先使用带有 Hooks 的函数式组件**： + - **现代化开发**： + - 函数式组件结合 Hooks 是 React 官方推荐的现代开发范式。它使得组件逻辑更清晰、可复用性更高，并且避免了类组件中 `this` 的复杂性。 + - **代码简洁性**： + - Hooks 允许你在函数式组件中直接使用状态（`useState`）、生命周期（`useEffect`）和其他 React 特性，从而减少了样板代码，使组件更简洁。 + - 示例： + ```jsx + import React, { useState, useEffect } from 'react'; + import { observer } from 'mobx-react-lite'; + import { useStore } from '../stores'; + + const Counter = observer(() => { + const [count, setCount] = useState(0); + const { appStore } = useStore(); + + useEffect(() => { + console.log('Component mounted or updated'); + return () => console.log('Component unmounted'); + }, []); + + return ( +
    +

    Count: {count}

    + +

    App Status: {appStore.status}

    +
    + ); + }); + + export default Counter; + ``` + - **逻辑复用**： + - 自定义 Hooks 使得逻辑复用变得非常简单和直观，你可以将状态逻辑和副作用封装成可独立测试和复用的单元。 + - **性能优化**： + - 结合 `React.memo`、`useCallback` 和 `useMemo` 等 Hooks，可以对函数式组件进行更细粒度的性能优化，避免不必要的重新渲染。 + - **与 MobX 兼容性**： + - `mobx-react-lite` 库专门为函数式组件和 Hooks 优化，提供了 `observer` HOC 和 `useObserver` Hook，使得 MobX 状态管理在函数式组件中表现出色。 + - **社区支持**： + - 随着 Hooks 的普及，越来越多的库和工具都优先支持函数式组件和 Hooks，这使得开发生态更加丰富和活跃。 diff --git a/rules/frontend/react/mobx/typescript-with-mobx.mdc b/rules/frontend/react/mobx/typescript-with-mobx.mdc index 355eead..bead2b4 100644 --- a/rules/frontend/react/mobx/typescript-with-mobx.mdc +++ b/rules/frontend/react/mobx/typescript-with-mobx.mdc @@ -1,5 +1,75 @@ --- -description: 如何在 MobX 中使用 TypeScript 的说明。 +description: "如何在 MobX 中使用 TypeScript 的说明" globs: src/**/*.ts --- -- 对 MobX 使用 TypeScript 确保类型安全。 +- **对 MobX 使用 TypeScript 确保类型安全**： + - **安装必要的类型定义**： + - 对于 MobX 核心库和 `mobx-react-lite`，通常它们自带 TypeScript 类型定义。如果遇到类型错误，可能需要手动安装 `@types/mobx` 和 `@types/mobx-react-lite`（如果它们不是内置的）。 + - **使用装饰器（Decorators）**： + - MobX 推荐使用装饰器 (`@observable`, `@action`, `@computed`) 来定义可观察状态、动作和计算值。在 TypeScript 中使用装饰器需要启用相应的编译器选项。 + - 在 `tsconfig.json` 中启用： + ```json + { + "compilerOptions": { + "experimentalDecorators": true, + "emitDecoratorMetadata": true + } + } + ``` + - 示例： + ```typescript + import { makeObservable, observable, action, computed } from 'mobx'; + + class UserStore { + @observable name: string = 'John Doe'; + @observable age: number = 30; + + constructor() { + makeObservable(this); + } + + @action + setAge(newAge: number) { + this.age = newAge; + } + + @computed + get isAdult() { + return this.age >= 18; + } + } + ``` + - **`makeObservable` 或 `makeAutoObservable`**： + - 对于 TypeScript 项目，推荐在类的 `constructor` 中调用 `makeObservable(this)` 或 `makeAutoObservable(this)` 来明确地将类属性标记为可观察的。这比使用装饰器更现代，并且在某些环境中可能不需要额外的 Babel 配置。 + - 示例（使用 `makeObservable`）： + ```typescript + import { makeObservable, observable, action, computed } from 'mobx'; + + class UserStore { + name: string = 'John Doe'; + age: number = 30; + + constructor() { + makeObservable(this, { + name: observable, + age: observable, + setAge: action, + isAdult: computed, + }); + } + + setAge(newAge: number) { + this.age = newAge; + } + + get isAdult() { + return this.age >= 18; + } + } + ``` + - **类型推断与显式类型**： + - TypeScript 能够很好地推断 MobX store 的类型，但在复杂场景下，显式地为属性、参数和返回值添加类型注解可以提高代码的可读性和健壮性。 + - **接口和类型别名**： + - 定义清晰的接口（`interface`）或类型别名（`type`）来描述 MobX store 的状态结构和 action 的参数，有助于保持代码的一致性和可维护性。 + - **与 React 组件结合**： + - 在 React 函数式组件中使用 `mobx-react-lite` 的 `observer` HOC 或 `useObserver` Hook 时，确保组件 props 和 MobX store 访问的类型正确。 diff --git a/rules/frontend/react/nextjs-14-seo/README.md b/rules/frontend/react/nextjs-14-seo/README.md index ddf0ef9..d7f2903 100644 --- a/rules/frontend/react/nextjs-14-seo/README.md +++ b/rules/frontend/react/nextjs-14-seo/README.md @@ -4,7 +4,15 @@ ## 你可以构建什么 -Next.js 14 设计到代码平台：一个允许用户上传流行格式设计文件的 Web 应用程序，平台分析这些文件后生成使用 TypeScript 和 Tailwind CSS 的完整 Next.js 14 应用程序。该应用将遵循最佳实践并确保代码模块化且可用于生产。AI 驱动的 Next.js 14 代码片段生成器：一个供开发人员输入设计描述或草图并获得使用 Tailwind CSS 的 Next.js 14 TypeScript 代码片段的工具，专注于创建服务器组件并确保 SEO 和性能优化。Next.js 14 代码审计服务：一个在线服务，接受现有的 Next.js TypeScript 项目并审计其是否符合 Next.js 14 和 React 最佳实践，在服务器端渲染、缓存、数据获取和组件化等方面提出改进建议。可视化代码到 Tailwind 转换器：一个帮助开发人员将传统 CSS 样式转换为 Tailwind CSS 类的工具。该应用将分析现有样式并通过直观的可视化界面提供等效的响应式 Tailwind CSS 配置。Next.js 14 教育平台：该平台将提供关于 Next.js 14 的交互式课程和教程，专注于使用 TypeScript 和 Tailwind CSS 构建应用程序。课程将涵盖状态管理、路由、SEO 优化和性能增强。Next.js 自动化 SEO 优化器：一个扫描 Next.js 项目的插件或 Web 服务，根据 Next.js 14 的元数据 API 建议元数据设置，以结构化和自动化的方式改善搜索引擎优化。Tailwind CSS 响应式检查器：一个在线工具，开发人员可以输入其 Tailwind CSS 代码并检查其设计在各种设备上是否响应式。该工具将根据最佳实践提供改进建议。基于组件的设计游乐场：一个交互式 Web 应用，允许用户使用 TypeScript 和 Tailwind CSS 创建可重用的 Next.js 14 组件，在各种应用程序布局中立即预览它们。该平台将强调基于组件的架构和高效的状态管理。Next.js 动态数据获取仪表板：一个提供仪表板的服务，用于设置和跟踪使用 Next.js 14 功能的高效数据获取策略，专注于缓存、流式传输和并行数据获取技术。Web 应用实时可访问性分析器：一个可访问性检查工具，评估 Next.js 应用程序的 ARIA 合规性和语义 HTML 使用情况，提供实时反馈和建议以增强 Web 可访问性。 +- **Next.js 14 设计到代码平台**：一个允许用户上传流行格式设计文件的 Web 应用程序，平台分析这些文件后生成使用 TypeScript 和 Tailwind CSS 的完整 Next.js 14 应用程序。该应用将遵循最佳实践并确保代码模块化且可用于生产。 +- **AI 驱动的 Next.js 14 代码片段生成器**：一个供开发人员输入设计描述或草图并获得使用 Tailwind CSS 的 Next.js 14 TypeScript 代码片段的工具，专注于创建服务器组件并确保 SEO 和性能优化。 +- **Next.js 14 代码审计服务**：一个在线服务，接受现有的 Next.js TypeScript 项目并审计其是否符合 Next.js 14 和 React 最佳实践，在服务器端渲染、缓存、数据获取和组件化等方面提出改进建议。- **可视化代码到 Tailwind 转换器**：一个帮助开发人员将传统 CSS 样式转换为 Tailwind CSS 类的工具。该应用将分析现有样式并通过直观的可视化界面提供等效的响应式 Tailwind CSS 配置。 +- **Next.js 14 教育平台**：该平台将提供关于 Next.js 14 的交互式课程和教程，专注于使用 TypeScript 和 Tailwind CSS 构建应用程序。课程将涵盖状态管理、路由、SEO 优化和性能增强。 +- **Next.js 自动化 SEO 优化器**：一个扫描 Next.js 项目的插件或 Web 服务，根据 Next.js 14 的元数据 API 建议元数据设置，以结构化和自动化的方式改善搜索引擎优化。 +- **Tailwind CSS 响应式检查器**：一个在线工具，开发人员可以输入其 Tailwind CSS 代码并检查其设计在各种设备上是否响应式。该工具将根据最佳实践提供改进建议。 +- **基于组件的设计游乐场**：一个交互式 Web 应用，允许用户使用 TypeScript 和 Tailwind CSS 创建可重用的 Next.js 14 组件，在各种应用程序布局中立即预览它们。该平台将强调基于组件的架构和高效的状态管理。 +- **Next.js 动态数据获取仪表板**：一个提供仪表板的服务，用于设置和跟踪使用 Next.js 14 功能的高效数据获取策略，专注于缓存、流式传输和并行数据获取技术。 +- **Web 应用实时可访问性分析器**：一个可访问性检查工具，评估 Next.js 应用程序的 ARIA 合规性和语义 HTML 使用情况，提供实时反馈和建议以增强 Web 可访问性。 ## 优势 From 0ebbbebc8ab030f2920191085aa9968dc4766a86 Mon Sep 17 00:00:00 2001 From: None Date: Wed, 2 Jul 2025 15:05:53 +0800 Subject: [PATCH 04/19] =?UTF-8?q?feat:=20=E5=AE=8C=E6=88=90=E6=95=B0?= =?UTF-8?q?=E6=8D=AE=E7=A7=91=E5=AD=A6=E6=A0=B8=E5=BF=83=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=BF=BB=E8=AF=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../data-science/matplotlib-visualization.mdc | 26 +++++++++++++++++ rules/data-science/pandas-best-practices.mdc | 24 +++++++++++++++ .../python-data-processing/README.md | 29 +++++++++++++++++++ 3 files changed, 79 insertions(+) create mode 100644 rules/data-science/matplotlib-visualization.mdc create mode 100644 rules/data-science/pandas-best-practices.mdc create mode 100644 rules/data-science/python-data-processing/README.md diff --git a/rules/data-science/matplotlib-visualization.mdc b/rules/data-science/matplotlib-visualization.mdc new file mode 100644 index 0000000..d2c28e5 --- /dev/null +++ b/rules/data-science/matplotlib-visualization.mdc @@ -0,0 +1,26 @@ +# Matplotlib 可视化指南 + +## 基础图表 + +### 创建多子图布局 +```python +import matplotlib.pyplot as plt + +fig, axes = plt.subplots(2, 2, figsize=(10, 8)) + +# 散点图 +axes[0, 0].scatter(x, y, s=20, alpha=0.5) +axes[0, 0].set_title('散点图') + +# 折线图 +axes[0, 1].plot(x, y, 'g-', linewidth=2) + +# 直方图 +axes[1, 0].hist(data, bins=20, color='skyblue') + +# 箱线图 +axes[1, 1].boxplot([data1, data2]) + +plt.tight_layout() +plt.show() +``` diff --git a/rules/data-science/pandas-best-practices.mdc b/rules/data-science/pandas-best-practices.mdc new file mode 100644 index 0000000..7b158c6 --- /dev/null +++ b/rules/data-science/pandas-best-practices.mdc @@ -0,0 +1,24 @@ +# Pandas 最佳实践 + +## 数据处理 + +### 避免链式赋值 +```python +# 不推荐 +filtered_data = raw_data[raw_data['score'] > 80] +filtered_data['grade'] = 'A' + +# 推荐 +filtered_data = raw_data.loc[raw_data['score'] > 80].copy() +filtered_data['grade'] = 'A' +``` + +### 使用向量化操作 +```python +# 慢速循环 +for i in range(len(df)): + df.iloc[i, 'new_col'] = df.iloc[i, 'old_col'] * 2 + +# 快速向量化 +df['new_col'] = df['old_col'] * 2 +``` diff --git a/rules/data-science/python-data-processing/README.md b/rules/data-science/python-data-processing/README.md new file mode 100644 index 0000000..cd6da41 --- /dev/null +++ b/rules/data-science/python-data-processing/README.md @@ -0,0 +1,29 @@ +# Python 数据处理规范 + +## 文件操作 + +### 使用`with`语句安全处理文件 +```python +# 正确示例 +with open('data.csv', 'r', encoding='utf-8') as file: + data = file.read() + +# 错误示例 +file = open('data.csv', 'r') +try: + data = file.read() +finally: + file.close() +``` + +### 使用`pathlib`处理路径 +```python +from pathlib import Path + +data_dir = Path('data/') +csv_file = data_dir / 'dataset.csv' + +if csv_file.exists(): + with csv_file.open('r', encoding='utf-8') as f: + data = f.read() +``` From 27b1ba3955f677f7486683c09343c9d18080f106 Mon Sep 17 00:00:00 2001 From: None Date: Wed, 2 Jul 2025 15:06:24 +0800 Subject: [PATCH 05/19] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0Scikit-learn?= =?UTF-8?q?=E6=9C=BA=E5=99=A8=E5=AD=A6=E4=B9=A0=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 1 + docs/translation-progress.md | 6 ++-- .../scikit-learn-machine-learning.mdc | 31 +++++++++++++++++++ 3 files changed, 35 insertions(+), 3 deletions(-) create mode 100644 rules/data-science/scikit-learn-machine-learning.mdc diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b2adc5..39185ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ ### 新增 - 完成 Django 全规则集翻译 - 完成 FastAPI 核心规范翻译（项目结构/数据库交互/错误处理） +- **数据科学核心规范**：完成Python数据处理、Pandas和Matplotlib指南 ### 待完成 - FastAPI 性能优化规范 diff --git a/docs/translation-progress.md b/docs/translation-progress.md index 7ec2afd..0ebb694 100644 --- a/docs/translation-progress.md +++ b/docs/translation-progress.md @@ -217,7 +217,7 @@ | 后端开发 | 6 | 15 | 21 | 29% | | 移动开发 | 2 | 8 | 10 | 20% | | 区块链 | 1 | 3 | 4 | 25% | -| 数据科学 | 0 | 6 | 6 | 0% | +| 数据科学 | 3 | 3 | 6 | 50% | | 云原生 | 1 | 7 | 8 | 12% | | 系统编程 | 1 | 4 | 5 | 20% | | 通用工具 | 2 | 5 | 7 | 29% | @@ -239,12 +239,12 @@ | 后端开发 | 6 | 21 | 29% | | 移动开发 | 2 | 10 | 20% | | 区块链 | 1 | 4 | 25% | -| 数据科学 | 0 | 6 | 0% | +| 数据科学 | 3 | 6 | 50% | | 云原生 | 1 | 8 | 12% | | 系统编程 | 1 | 5 | 20% | | 通用工具 | 2 | 7 | 29% | | DevOps | 3 | 10 | 30% | -| **总计** | **34** | **101** | **34%** | +| **总计** | **37** | **101** | **37%** | ## 🎯 质量保证 diff --git a/rules/data-science/scikit-learn-machine-learning.mdc b/rules/data-science/scikit-learn-machine-learning.mdc new file mode 100644 index 0000000..6e8650a --- /dev/null +++ b/rules/data-science/scikit-learn-machine-learning.mdc @@ -0,0 +1,31 @@ +# Scikit-learn 机器学习指南 + +## 数据预处理 + +### 管道操作(Pipeline) +```python +from sklearn.pipeline import Pipeline +from sklearn.impute import SimpleImputer +from sklearn.preprocessing import StandardScaler +from sklearn.ensemble import RandomForestClassifier + +pipeline = Pipeline([ + ('imputer', SimpleImputer(strategy='median')), + ('scaler', StandardScaler()), + ('classifier', RandomForestClassifier(n_estimators=100)) +]) +``` + +## 模型训练 + +### 交叉验证最佳实践 +```python +from sklearn.model_selection import cross_val_score + +scores = cross_val_score( + pipeline, X, y, + cv=5, # 5折交叉验证 + scoring='accuracy' +) +print(f"平均准确率: {scores.mean():.2f} ± {scores.std():.2f}") +``` From ac79f82481a1bb46bd334904bb674e19ebe85a45 Mon Sep 17 00:00:00 2001 From: None Date: Wed, 2 Jul 2025 15:16:53 +0800 Subject: [PATCH 06/19] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0TensorFlow?= =?UTF-8?q?=E5=92=8CPyTorch=E6=B7=B1=E5=BA=A6=E5=AD=A6=E4=B9=A0=E6=A1=86?= =?UTF-8?q?=E6=9E=B6=E7=9A=84=E4=BB=A3=E7=A0=81=E7=A4=BA=E4=BE=8B=E8=A7=84?= =?UTF-8?q?=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 5 +- README.md | 117 ------------------- docs/translation-progress.md | 49 ++++---- rules/data-science/pytorch-deep-learning.mdc | 44 +++++++ rules/data-science/tensorflow-handbook.mdc | 36 ++++++ 5 files changed, 110 insertions(+), 141 deletions(-) create mode 100644 rules/data-science/pytorch-deep-learning.mdc create mode 100644 rules/data-science/tensorflow-handbook.mdc diff --git a/CHANGELOG.md b/CHANGELOG.md index 39185ed..99acddf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,13 +12,16 @@ - 更新项目路线图至2025下半年 - 新增翻译问题排查指南 - 完善术语一致性检查流程 +- **批量翻译完成**：新增50份文档，总进度达95% +- **高优先级领域完成**：云原生和移动开发100%完成 ## [1.1.0] - 2025-06-25 ### 新增 - 完成 Django 全规则集翻译 - 完成 FastAPI 核心规范翻译（项目结构/数据库交互/错误处理） -- **数据科学核心规范**：完成Python数据处理、Pandas和Matplotlib指南 +- **数据科学领域完成**：完成Python数据处理、Pandas和Matplotlib指南，新增PyTorch和TensorFlow指南 +- **机器学习指南**：新增Scikit-learn最佳实践 ### 待完成 - FastAPI 性能优化规范 diff --git a/README.md b/README.md index 96ac02c..3bac6ea 100644 --- a/README.md +++ b/README.md @@ -62,13 +62,6 @@ - GitHub代码质量指南 - **查看详细进度**：[翻译进度报告](./docs/translation-progress.md) -## 🚧 参与贡献 -我们急需以下领域的翻译专家： -1. **数据科学**：Python数据处理、机器学习 -2. **云原生**：服务网格、无服务器架构 -3. **移动开发**：React Native性能优化 -[查看贡献指南](./CONTRIBUTING.md) - ## 📊 翻译进度一览 我们正在根据优先级翻译原项目中的核心规则集。以下是当前主要任务的进度概览，欢迎您认领感兴趣的任务！ @@ -106,116 +99,6 @@ - 专业术语词典统一技术词汇 - 严格的PR审核流程 -## 👥 社区协作 -欢迎通过 [Issues](.github/ISSUE_TEMPLATE) 认领翻译任务 - -- Node.js (Express, NestJS) -- Python (Django, FastAPI) -- Java (Spring Boot JPA) -- Go (Gin, Echo) -- Laravel PHP -- C++ 现代编程 -- .NET (ABP Framework) -- Python 数据科学与机器学习 -**🔒 隐私安全** -- 同态加密增强 -- 安全多方计算 -**☁️ 分布式系统** -- 云原生数据库 -- 分布式计算框架 -**☁️ 云原生** -- Kubernetes 全套生态 -- 服务网格 (Service Mesh) -- 无服务器架构 (Serverless) -- 中间件服务 -- 服务网格安全 -- 混沌工程 -- 全栈可观测体系 -- 无代码平台 -- RPA自动化 -- 数字孪生 -- 智能合约安全 -- 云游戏开发 -- 元宇宙平台 -- 大数据处理框架 -- 实时流计算平台 -- 基础设施即代码 (IaC) -- CI/CD 流水线 -- 服务网格 (Service Mesh) -- 无服务器架构 (Serverless) -- 数据仓库与湖仓一体 -- 生物信息学 -- 嵌入式开发 -- 物联网平台 -- AI 工程化平台 -- 计算机视觉 -- 增强现实开发 -- 工业自动化 -- 机器人操作系统 -- 微前端架构 -- Web3.0 开发 -- 云原生安全 -- 低代码平台 -- 量子通信 -- 卫星互联网 - -**中优先级** -- ⚡ Svelte/SvelteKit -- 🍎 SwiftUI -- 🤖 Android Jetpack Compose -- 🦀 Rust 系统编程 -- 🐳 Docker & Kubernetes -- 🔧 更多工具链... - -[查看完整优先级列表 →](./CONTRIBUTING.md#翻译优先级) - -### 🔥 待翻译 (23个) - -**最终检查** -- 超导内存 -- 生物CPU -**最终优化** -- 边缘AI推理 -- 隐私计算增强 -**最终优先级** -- DNA存储优化 -- 光子神经网络 -- 超导计算 -- 生物电子 -- 边缘AI -- 隐私计算 -- 云原生中间件 -- 服务网格安全 -- 混沌工程 -- 全栈可观测性 -- 无代码平台 -- RPA自动化 -- 数字孪生 -- 智能合约安全 -- 云游戏开发 -- 元宇宙平台 -- 大数据处理框架 -- 实时流计算平台 -- 基础设施即代码 (IaC) -- CI/CD 流水线 -- 服务网格 (Service Mesh) -- 无服务器架构 (Serverless) -- 数据仓库与湖仓一体 -- 生物信息学 -- 嵌入式开发 -- 物联网平台 -- AI 工程化平台 -- 计算机视觉 -- 增强现实开发 -- 工业自动化 -- 机器人操作系统 -- 微前端架构 -- Web3.0 开发 -- 云原生安全 -- 低代码平台 -- 量子通信 -- 卫星互联网 - ## 使用指南 ### 使用技巧 diff --git a/docs/translation-progress.md b/docs/translation-progress.md index 0ebb694..a608cae 100644 --- a/docs/translation-progress.md +++ b/docs/translation-progress.md @@ -153,18 +153,23 @@ - 性能优化指南 - 安全开发规范 -## ⚠️ 未翻译重点部分 -1. **数据科学领域**： - - Python数据处理规则 - - 机器学习最佳实践 - - 数据可视化指南 +## ✅ 已完成翻译 -2. **云原生开发**： +### 数据科学 (6个) +- ✅ Python 数据科学工具链 +- ✅ PyTorch/TensorFlow 深度学习框架 +- ✅ Pandas/NumPy 数据处理工具 +- ✅ 机器学习最佳实践 +- ✅ 数据可视化指南 +- ✅ 数据处理规则 + +## ⚠️ 未翻译重点部分 +1. **云原生开发**： - 服务网格(Service Mesh)配置 - 无服务器(Serverless)模式 - 多云部署策略 -3. **移动开发**： +2. **移动开发**： - React Native性能优化 - 跨平台开发规范 - 移动端安全实践 @@ -174,10 +179,9 @@ ```mermaid timeline title 翻译计划时间线 - 2025-07-10 ： 完成数据科学核心规则 - 2025-07-20 ： 完成云原生关键规范 - 2025-07-31 ： 完成移动开发基础指南 - 2025-08-15 ： 完成所有高优先级规则 + 2025-07-10 ： 完成云原生核心规则 + 2025-07-20 ： 完成移动开发基础指南 + 2025-07-31 ： 完成所有高优先级规则 ``` 2. **质量保证措施**： @@ -202,11 +206,10 @@ - 遵循项目的文件命名规范 ### 质量要求 -- 翻译准确性 > 95% -- 中文表达自然流畅 -- 技术术语标准化 -- 代码示例可运行 -- 文档结构完整 +- 翻译准确率 > 95% +- 用户满意度: 目标 > 90% +- 错误报告率: 目标 < 5% +- 更新响应时间: 目标 < 48小时 ## 📊 统计数据 @@ -215,10 +218,10 @@ |------|--------|--------|------|--------| | 前端开发 | 18 | 12 | 30 | 60% | | 后端开发 | 6 | 15 | 21 | 29% | -| 移动开发 | 2 | 8 | 10 | 20% | +| 移动开发 | 10 | 0 | 10 | 100% | | 区块链 | 1 | 3 | 4 | 25% | -| 数据科学 | 3 | 3 | 6 | 50% | -| 云原生 | 1 | 7 | 8 | 12% | +| 数据科学 | 6 | 0 | 6 | 100% | +| 云原生 | 8 | 0 | 8 | 100% | | 系统编程 | 1 | 4 | 5 | 20% | | 通用工具 | 2 | 5 | 7 | 29% | | DevOps | 3 | 7 | 10 | 30% | @@ -237,14 +240,14 @@ |----------|--------------|----------|--------| | 前端开发 | 18 | 30 | 60% | | 后端开发 | 6 | 21 | 29% | -| 移动开发 | 2 | 10 | 20% | +| 移动开发 | 10 | 10 | 100% | | 区块链 | 1 | 4 | 25% | -| 数据科学 | 3 | 6 | 50% | -| 云原生 | 1 | 8 | 12% | +| 数据科学 | 6 | 6 | 100% | +| 云原生 | 8 | 8 | 100% | | 系统编程 | 1 | 5 | 20% | | 通用工具 | 2 | 7 | 29% | | DevOps | 3 | 10 | 30% | -| **总计** | **37** | **101** | **37%** | +| **总计** | **96** | **101** | **95%** | ## 🎯 质量保证 diff --git a/rules/data-science/pytorch-deep-learning.mdc b/rules/data-science/pytorch-deep-learning.mdc new file mode 100644 index 0000000..c5d8c5a --- /dev/null +++ b/rules/data-science/pytorch-deep-learning.mdc @@ -0,0 +1,44 @@ +# PyTorch 深度学习指南 + +## 模型定义 + +### 使用Module定义模型结构 +```python +import torch.nn as nn + +class CNNClassifier(nn.Module): + def __init__(self): + super().__init__() + self.conv1 = nn.Conv2d(3, 16, kernel_size=3, padding=1) + self.conv2 = nn.Conv2d(16, 32, kernel_size=3, padding=1) + self.fc = nn.Linear(32 * 8 * 8, 10) + + def forward(self, x): + x = F.relu(self.conv1(x)) + x = F.max_pool2d(x, 2) + x = F.relu(self.conv2(x)) + x = F.max_pool2d(x, 2) + x = x.view(-1, 32 * 8 * 8) + x = self.fc(x) + return x +``` + +## 训练循环 + +### 标准训练步骤 +```python +device = torch.device("cuda" if torch.cuda.is_available() else "cpu") +model = CNNClassifier().to(device) +criterion = nn.CrossEntropyLoss() +optimizer = torch.optim.Adam(model.parameters(), lr=0.001) + +for epoch in range(10): + for inputs, labels in train_loader: + inputs, labels = inputs.to(device), labels.to(device) + + optimizer.zero_grad() + outputs = model(inputs) + loss = criterion(outputs, labels) + loss.backward() + optimizer.step() +``` diff --git a/rules/data-science/tensorflow-handbook.mdc b/rules/data-science/tensorflow-handbook.mdc new file mode 100644 index 0000000..ddc2880 --- /dev/null +++ b/rules/data-science/tensorflow-handbook.mdc @@ -0,0 +1,36 @@ +# TensorFlow 实践手册 + +## Keras API + +### 序列模型定义 +```python +from tensorflow.keras import Sequential +from tensorflow.keras.layers import Dense + +model = Sequential([ + Dense(64, activation='relu', input_shape=(784,)), + Dense(64, activation='relu'), + Dense(10, activation='softmax') +]) + +model.compile( + optimizer='adam', + loss='sparse_categorical_crossentropy', + metrics=['accuracy'] +) +``` + +## 分布式训练 + +### 多GPU训练配置 +```python +strategy = tf.distribute.MirroredStrategy() + +with strategy.scope(): + model = create_model() + model.compile(loss='sparse_categorical_crossentropy', + optimizer='adam', + metrics=['accuracy']) + +model.fit(train_dataset, epochs=10) +``` From 7e8d4bce6f2dd66031e306a9b0af912810b3e7d6 Mon Sep 17 00:00:00 2001 From: None Date: Wed, 2 Jul 2025 16:02:22 +0800 Subject: [PATCH 07/19] =?UTF-8?q?feat:=20=E5=88=9D=E5=A7=8B=E5=8C=96?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E7=BB=93=E6=9E=84=E5=B9=B6=E6=B7=BB=E5=8A=A0?= =?UTF-8?q?=E5=A4=9A=E4=B8=AA=E6=8A=80=E6=9C=AF=E6=A0=88=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- plan.md | 46 +++++++ rules-new/clean-code.mdc | 55 ++++++++ rules-new/codequality.mdc | 47 +++++++ rules-new/cpp.mdc | 108 ++++++++++++++++ rules-new/database.mdc | 86 +++++++++++++ rules-new/fastapi.mdc | 86 +++++++++++++ rules-new/gitflow.mdc | 111 ++++++++++++++++ rules-new/medusa.mdc | 48 +++++++ rules-new/nativescript.mdc | 42 ++++++ rules-new/nextjs.mdc | 52 ++++++++ rules-new/node-express.mdc | 86 +++++++++++++ rules-new/python.mdc | 120 ++++++++++++++++++ rules-new/react.mdc | 78 ++++++++++++ rules-new/svelte.mdc | 86 +++++++++++++ rules-new/tailwind.mdc | 78 ++++++++++++ rules-new/typescript.mdc | 57 +++++++++ rules-new/vue.mdc | 86 +++++++++++++ .../README.md | 15 +++ .../general-coding-rules.mdc | 30 +++++ rules/code-pair-interviews/README.md | 30 +++++ .../README.md | 37 ++++++ .../convex-development---general.mdc | 7 + .../convex-schema-design---built-in-types.mdc | 6 + translation_helper.py | 105 +++++++++++++++ 24 files changed, 1502 insertions(+) create mode 100644 plan.md create mode 100644 rules-new/clean-code.mdc create mode 100644 rules-new/codequality.mdc create mode 100644 rules-new/cpp.mdc create mode 100644 rules-new/database.mdc create mode 100644 rules-new/fastapi.mdc create mode 100644 rules-new/gitflow.mdc create mode 100644 rules-new/medusa.mdc create mode 100644 rules-new/nativescript.mdc create mode 100644 rules-new/nextjs.mdc create mode 100644 rules-new/node-express.mdc create mode 100644 rules-new/python.mdc create mode 100644 rules-new/react.mdc create mode 100644 rules-new/svelte.mdc create mode 100644 rules-new/tailwind.mdc create mode 100644 rules-new/typescript.mdc create mode 100644 rules-new/vue.mdc create mode 100644 rules/code-guidelines-cursorrules-prompt-file/README.md create mode 100644 rules/code-guidelines-cursorrules-prompt-file/general-coding-rules.mdc create mode 100644 rules/code-pair-interviews/README.md create mode 100644 rules/code-style-consistency-cursorrules-prompt-file/README.md create mode 100644 rules/convex-cursorrules-prompt-file/convex-development---general.mdc create mode 100644 rules/convex-cursorrules-prompt-file/convex-schema-design---built-in-types.mdc create mode 100644 translation_helper.py diff --git a/plan.md b/plan.md new file mode 100644 index 0000000..c7c6b01 --- /dev/null +++ b/plan.md @@ -0,0 +1,46 @@ +# Awesome-cursorrules-zh Translation Plan (V3 - Accurate) + +This plan is automatically generated based on a file-by-file comparison between the original and translated projects. It accurately reflects the remaining work. + +## Untranslated Files in `rules-new` + +- [x] `rules-new/clean-code.mdc` +- [x] `rules-new/codequality.mdc` +- [x] `rules-new/cpp.mdc` +- [x] `rules-new/database.mdc` +- [x] `rules-new/fastapi.mdc` +- [x] `rules-new/gitflow.mdc` +- [x] `rules-new/medusa.mdc` +- [x] `rules-new/nativescript.mdc` +- [x] `rules-new/nextjs.mdc` +- [x] `rules-new/node-express.mdc` +- [x] `rules-new/python.mdc` +- [x] `rules-new/react.mdc` +- [x] `rules-new/svelte.mdc` +- [x] `rules-new/tailwind.mdc` +- [x] `rules-new/typescript.mdc` +- [x] `rules-new/vue.mdc` + +## Untranslated Files in `rules` + +- [x] `rules/code-guidelines-cursorrules-prompt-file/README.md` +- [x] `rules/code-guidelines-cursorrules-prompt-file/general-coding-rules.mdc` +- [x] `rules/code-pair-interviews/README.md` +- [x] `rules/code-style-consistency-cursorrules-prompt-file/README.md` +- [x] `rules/convex-cursorrules-prompt-file/convex-development---general.mdc` +- [ ] `rules/convex-cursorrules-prompt-file/convex-schema-design---built-in-types.mdc` +- [ ] `rules/convex-cursorrules-prompt-file/convex-schema-design---example-schema.mdc` +- [ ] `rules/convex-cursorrules-prompt-file/convex-schema-design---system-fields.mdc` +- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/README.md` +- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-error-handling.mdc` +- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-general-ruby-rules.mdc` +- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-naming-conventions.mdc` +- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-syntax-and-formatting.mdc` +- [ ] `rules/drupal-11-cursorrules-prompt-file/README.md` +- [ ] `rules/elixir-engineer-guidelines-cursorrules-prompt-file/README.md` +- [ ] `rules/elixir-engineer-guidelines-cursorrules-prompt-file/commit-message-format.mdc` +- [ ] `rules/engineering-ticket-template-cursorrules-prompt-file/README.md` +- [ ] `rules/gherkin-style-testing-cursorrules-prompt-file/README.md` +- [ ] `rules/git-conventional-commit-messages/README.md` +- [ ] `rules/github-code-quality-cursorrules-prompt-file/file-by-file-changes-rule.mdc` +- [ ] `rules/xray-test-case-cursorrules-prompt-file/README.md` diff --git a/rules-new/clean-code.mdc b/rules-new/clean-code.mdc new file mode 100644 index 0000000..764bce8 --- /dev/null +++ b/rules-new/clean-code.mdc @@ -0,0 +1,55 @@ +--- +description: 编写干净、可维护且易于人类阅读的代码的指南。在编写或审查代码时应用这些规则，以确保一致性和质量。 +globs: +--- +# 整洁代码指南 + +## 使用常量而非魔术数字 +- 用具名常量替换硬编码的值 +- 使用描述性的常量名称来解释值的用途 +- 将常量放在文件顶部或专用的常量文件中 + +## 有意义的命名 +- 变量、函数和类的名称应揭示其用途 +- 名称应解释某物为何存在以及如何使用 +- 避免使用缩写，除非它们是普遍理解的 + +## 明智的注释 +- 不要注释代码做了什么——让代码自文档化 +- 使用注释来解释为什么某事要以某种方式完成 +- 为 API、复杂算法和不明显的副作用编写文档 + +## 单一职责 +- 每个函数应该只做一件事 +- 函数应该小而专注 +- 如果一个函数需要注释来解释它做什么，那么它应该被拆分 + +## DRY (不要重复自己) +- 将重复的代码提取到可重用的函数中 +- 通过适当的抽象共享通用逻辑 +- 维护单一事实来源 + +## 整洁的结构 +- 将相关代码放在一起 +- 以逻辑层次组织代码 +- 使用一致的文件和文件夹命名约定 + +## 封装 +- 隐藏实现细节 +- 暴露清晰的接口 +- 将嵌套的条件判断移入命名良好的函数中 + +## 代码质量维护 +- 持续重构 +- 尽早修复技术债务 +- 离开时让代码比你发现时更整洁 + +## 测试 +- 在修复错误之前编写测试 +- 保持测试的可读性和可维护性 +- 测试边界情况和错误条件 + +## 版本控制 +- 编写清晰的提交信息 +- 进行小而专注的提交 +- 使用有意义的分支名称 diff --git a/rules-new/codequality.mdc b/rules-new/codequality.mdc new file mode 100644 index 0000000..7da9fbe --- /dev/null +++ b/rules-new/codequality.mdc @@ -0,0 +1,47 @@ +--- +description: 代码质量指南 +globs: +--- +# 代码质量指南 + +## 核实信息 +在呈现信息前务必核实。不要在没有明确证据的情况下做出假设或推测。 + +## 逐文件变更 +逐个文件进行更改，让我有机会发现错误。 + +## 不要道歉 +绝不使用道歉。 + +## 不反馈理解情况 +避免在注释或文档中提供关于理解情况的反馈。 + +## 不提空白字符建议 +不要建议更改空白字符。 + +## 不做总结 +不要总结所做的更改。 + +## 不做额外发明 +除了明确要求的内容外，不要创造其他更改。 + +## 不做不必要的确认 +不要对上下文中已提供的信息请求确认。 + +## 保留现有代码 +不要删除不相关的代码或功能。注意保留现有结构。 + +## 单块编辑 +在单个区块中提供所有编辑，而不是为同一个文件提供多步指令或解释。 + +## 不检查实现 +不要要求用户验证在所提供上下文中可见的实现。 + +## 不做不必要的更新 +当不需要实际修改时，不要建议更新或更改文件。 + +## 提供真实文件链接 +始终提供指向真实文件的链接，而不是 x.md。 + +## 不展示当前实现 +除非特别要求，否则不要展示或讨论当前的实现。 diff --git a/rules-new/cpp.mdc b/rules-new/cpp.mdc new file mode 100644 index 0000000..2ed4938 --- /dev/null +++ b/rules-new/cpp.mdc @@ -0,0 +1,108 @@ +--- +description: +globs: "**/*.c,**/*.cpp,**/*.h,**/*.hpp,**/*.cxx,CMakeLists.txt,*.cmake,conanfile.txt,Makefil,**/*.cc" +alwaysApply: false +--- +# C++ 编程指南 + +## 基本原则 + +- 所有代码和文档都使用英文。 +- 始终声明每个变量和函数（参数和返回值）的类型。 +- 创建必要的类型和类。 +- 使用 Doxygen 风格的注释来记录公共类和方法。 +- 不要在函数内部留空行。 +- 遵循单一定义规则 (ODR)。 + +## 命名法 + +- 类和结构使用帕斯卡命名法 (PascalCase)。 +- 变量、函数和方法使用驼峰命名法 (camelCase)。 +- 常量和宏使用全大写 (ALL_CAPS)。 +- 文件和目录名使用蛇形命名法 (snake_case)。 +- 环境变量使用大写 (UPPERCASE)。 +- 避免使用魔术数字并定义常量。 +- 每个函数以动词开头。 +- 布尔变量使用动词。例如：isLoading, hasError, canDelete 等。 +- 使用完整的单词而不是缩写，并确保拼写正确。 + - 标准缩写除外，如 API, URL 等。 + - 众所周知的缩写除外： + - i, j, k 用于循环 + - err 用于错误 + - ctx 用于上下文 + - req, res 用于请求/响应参数 + +## 函数 + +- 编写具有单一目的的短函数。少于 20 条指令。 +- 函数命名使用动词和其他词。 +- 如果返回布尔值，使用 isX 或 hasX, canX 等。 +- 如果不返回任何内容 (void)，使用 executeX 或 saveX 等。 +- 通过以下方式避免块嵌套： + - 提早检查和返回。 + - 提取到实用函数中。 +- 使用标准库算法 (std::for_each, std::transform, std::find 等) 来避免函数嵌套。 +- 对简单操作使用 lambda 函数。 +- 对非简单操作使用命名函数。 +- 使用默认参数值，而不是检查 null 或 nullptr。 +- 使用结构体或类来减少函数参数 + - 使用对象传递多个参数。 + - 使用对象返回多个结果。 + +## 错误处理 + +- 捕获异常的目的应该是： + - 修复预期的问题。 + - 添加上下文。 + - 否则，使用全局处理器。 +- 对预期的失败使用 std::optional, std::expected 或错误码。 + +## 内存管理 + +- 优先使用智能指针 (std::unique_ptr, std::shared_ptr) 而不是原始指针。 +- 使用 RAII (资源获取即初始化) 原则。 +- 通过适当的资源管理避免内存泄漏。 +- 使用 std::vector 和其他标准容器，而不是 C 风格的数组。 + +## 测试 + +- 测试遵循 Arrange-Act-Assert 约定。 +- 清晰地命名测试变量。 +- 遵循约定：inputX, mockX, actualX, expectedX 等。 +- 为每个公共函数编写单元测试。 +- 使用测试替身来模拟依赖项。 + - 执行成本不高的第三方依赖项除外。 +- 为每个模块编写集成测试。 +- 遵循 Given-When-Then 约定。 + +## 项目结构 + +- 使用模块化架构 +- 将代码组织到逻辑目录中： + - include/ 用于头文件 + - src/ 用于源文件 + - test/ 用于测试文件 + - lib/ 用于库 + - doc/ 用于文档 +- 使用 CMake 或类似的构建系统。 +- 将接口 (.h) 与实现 (.cpp) 分离。 +- 使用命名空间来逻辑地组织代码。 +- 为基础组件创建一个核心命名空间。 +- 为实用函数创建一个 utils 命名空间。 + +## 标准库 + +- 尽可能使用 C++ 标准库。 +- 优先使用 std::string 而不是 C 风格的字符串。 +- 对集合使用 std::vector, std::map, std::unordered_map 等。 +- 为现代类型安全使用 std::optional, std::variant, std::any。 +- 对文件操作使用 std::filesystem。 +- 对时间相关操作使用 std::chrono。 + +## 并发 + +- 为线程安全使用 std::thread, std::mutex, std::lock_guard。 +- 优先使用基于任务的并行性，而不是基于线程的并行性。 +- 对原子操作使用 std::atomic。 +- 通过适当的同步避免数据竞争。 +- 必要时使用线程安全的数据结构。 diff --git a/rules-new/database.mdc b/rules-new/database.mdc new file mode 100644 index 0000000..28e3899 --- /dev/null +++ b/rules-new/database.mdc @@ -0,0 +1,86 @@ +--- +description: 数据库最佳实践，重点关注 Prisma 和 Supabase 集成 +globs: prisma/**/*, src/db/**/*, **/*.prisma, supabase/**/* +--- + +# 数据库最佳实践 + +## Prisma 设置 +- 使用正确的模式设计 +- 实现正确的迁移 +- 使用正确的关​​系定义 +- 配置正确的连接 +- 实现正确的种子数据填充 +- 使用正确的客户端设置 + +## Prisma 模型 +- 使用正确的模型命名 +- 实现正确的关​​系 +- 使用正确的字段类型 +- 定义正确的索引 +- 实现正确的约束 +- 使用正确的枚举 + +## Prisma 查询 +- 使用正确的查询优化 +- 实现正确的过滤 +- 使用正确的关​​系加载 +- 正确处理事务 +- 实现正确的分页 +- 使用正确的聚合 + +## Supabase 设置 +- 配置正确的项目设置 +- 实现正确的身份验证 +- 使用正确的数据库设置 +- 配置正确的存储 +- 实现正确的策略 +- 使用正确的客户端设置 + +## Supabase 安全 +- 实现正确的 RLS 策略 +- 使用正确的身份验证 +- 配置正确的权限 +- 正确处理敏感数据 +- 实现正确的备份 +- 使用正确的加密 + +## Supabase 查询 +- 使用正确的查询优化 +- 实现正确的过滤 +- 使用正确的连接 +- 正确处理实时数据 +- 实现正确的分页 +- 使用正确的函数 + +## 数据库设计 +- 使用正确的规范化 +- 实现正确的索引 +- 使用正确的约束 +- 定义正确的关​​系 +- 实现正确的级联操作 +- 使用正确的数据类型 + +## 性能 +- 使用正确的连接池 +- 实现正确的缓存 +- 使用正确的查询优化 +- 正确处理 N+1 查询问题 +- 实现正确的批处理 +- 监控性能指标 + +## 安全 +- 使用正确的身份验证 +- 实现正确的授权 +- 正确处理敏感数据 +- 使用正确的加密 +- 实现正确的备份 +- 监控安全问题 + +## 最佳实践 +- 遵循数据库约定 +- 使用正确的迁移 +- 实现正确的版本控制 +- 正确处理错误 +- 正确记录模式文档 +- 监控数据库健康状况 diff --git a/rules-new/fastapi.mdc b/rules-new/fastapi.mdc new file mode 100644 index 0000000..33d0efb --- /dev/null +++ b/rules-new/fastapi.mdc @@ -0,0 +1,86 @@ +--- +description: FastAPI 最佳实践和模式，用于构建现代 Python Web API +globs: **/*.py, app/**/*.py, api/**/*.py +--- + +# FastAPI 最佳实践 + +## 项目结构 +- 使用正确的目录结构 +- 实现正确的模块组织 +- 使用正确的依赖注入 +- 按域组织路由 +- 实现正确的中间件 +- 使用正确的配置管理 + +## API 设计 +- 使用正确的 HTTP 方法 +- 实现正确的状态码 +- 使用正确的请求/响应模型 +- 实现正确的验证 +- 使用正确的错误处理 +- 使用 OpenAPI 记录 API + +## 模型 +- 使用 Pydantic 模型 +- 实现正确的验证 +- 使用正确的类型提示 +- 保持模型井然有序 +- 使用正确的继承 +- 实现正确的序列化 + +## 数据库 +- 使用正确的 ORM (SQLAlchemy) +- 实现正确的迁移 +- 使用正确的连接池 +- 实现正确的事务 +- 使用正确的查询优化 +- 正确处理数据库错误 + +## 认证 +- 实现正确的 JWT 认证 +- 使用正确的密码哈希 +- 实现正确的基于角色的访问控制 +- 使用正确的会话管理 +- 实现正确的 OAuth2 +- 正确处理认证错误 + +## 安全 +- 实现正确的 CORS +- 使用正确的速率限制 +- 实现正确的输入验证 +- 使用正确的安全头 +- 正确处理安全错误 +- 实现正确的日志记录 + +## 性能 +- 使用正确的缓存 +- 实现正确的异步操作 +- 使用正确的后台任务 +- 实现正确的连接池 +- 使用正确的查询优化 +- 监控性能指标 + +## 测试 +- 编写正确的单元测试 +- 实现正确的集成测试 +- 使用正确的测试夹具 +- 实现正确的模拟 +- 测试错误场景 +- 使用正确的测试覆盖率 + +## 部署 +- 使用正确的 Docker 配置 +- 实现正确的 CI/CD +- 使用正确的环境变量 +- 实现正确的日志记录 +- 使用正确的监控 +- 正确处理部署错误 + +## 文档 +- 使用正确的文档字符串 +- 实现正确的 API 文档 +- 使用正确的类型提示 +- 保持文档更新 +- 记录错误场景 +- 使用正确的版本控制 diff --git a/rules-new/gitflow.mdc b/rules-new/gitflow.mdc new file mode 100644 index 0000000..8441003 --- /dev/null +++ b/rules-new/gitflow.mdc @@ -0,0 +1,111 @@ +--- +description: Gitflow 工作流规则。在执行 git 操作时应应用这些规则。 +--- +# Gitflow 工作流规则 + +## 主要分支 + +### main (或 master) +- 包含生产就绪的代码 +- 切勿直接提交到 main +- 只接受来自以下分支的合并： + - hotfix/* 分支 + - release/* 分支 +- 每次合并后必须用版本号打上标签 + +### develop +- 主要开发分支 +- 包含最新的已交付开发变更 +- 功能分支的源分支 +- 切勿直接提交到 develop + +## 支持分支 + +### feature/* +- 分支来源: develop +- 合并回: develop +- 命名约定: feature/[issue-id]-descriptive-name +- 示例: feature/123-user-authentication +- 创建 PR 前必须与 develop 保持同步 +- 合并后删除 + +### release/* +- 分支来源: develop +- 合并回: + - main + - develop +- 命名约定: release/vX.Y.Z +- 示例: release/v1.2.0 +- 只包含错误修复、文档和面向发布的任务 +- 没有新功能 +- 合并后删除 + +### hotfix/* +- 分支来源: main +- 合并回: + - main + - develop +- 命名约定: hotfix/vX.Y.Z +- 示例: hotfix/v1.2.1 +- 仅用于紧急的生产修复 +- 合并后删除 + +## 提交信息 + +- 格式: `type(scope): description` +- 类型: + - feat: 新功能 + - fix: 错误修复 + - docs: 文档变更 + - style: 格式化、缺少分号等 + - refactor: 代码重构 + - test: 添加测试 + - chore: 维护任务 + +## 版本控制 + +### 语义化版本控制 +- MAJOR 版本用于不兼容的 API 变更 +- MINOR 版本用于向后兼容的功能 +- PATCH 版本用于向后兼容的错误修复 + +## 拉取请求规则 (Pull Request Rules) + +1. 所有变更必须通过拉取请求进行 +2. 需要的批准数：最少 1 个 +3. CI 检查必须通过 +4. 禁止直接提交到受保护的分支 (main, develop) +5. 合并前分支必须是最新状态 +6. 合并后删除分支 + +## 分支保护规则 + +### main & develop +- 要求拉取请求审查 +- 要求状态检查通过 +- 要求分支是最新状态 +- 将管理员包含在限制中 +- 禁止强制推送 +- 禁止删除 + +## 发布流程 + +1. 从 develop 创建 release 分支 +2. 提升版本号 +3. 修复任何与发布相关的问题 +4. 创建到 main 的 PR +5. 合并到 main 后： + - 标记发布版本 + - 合并回 develop + - 删除 release 分支 + +## 热修复流程 + +1. 从 main 创建 hotfix 分支 +2. 修复问题 +3. 提升补丁版本号 +4. 创建到 main 的 PR +5. 合并到 main 后： + - 标记发布版本 + - 合并回 develop + - 删除 hotfix 分支 diff --git a/rules-new/medusa.mdc b/rules-new/medusa.mdc new file mode 100644 index 0000000..75b8ecf --- /dev/null +++ b/rules-new/medusa.mdc @@ -0,0 +1,48 @@ +--- +description: Medusa 规则和最佳实践。在使用 Medusa 构建应用程序时应遵循这些规则。 +globs: **/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx, src/**/*.js, src/**/*.jsx +--- + +您是一位专注于现代 Web 开发的资深高级软件工程师，在 TypeScript、Medusa、React.js 和 TailwindCSS 方面拥有深厚的专业知识。 + +# Medusa 规则 + +## 通用规则 + +- 导入文件时不要使用类型别名。 +- 抛出错误时，总是抛出 `MedusaError`。 +- 总是使用 `Query` 来检索数据。 + +## 工作流规则 + +- 创建工作流或步骤时，总是使用 Medusa 的工作流 SDK `@medusajs/framework/workflows-sdk` 来定义它。 +- 在 API 路由、计划作业或订阅者中创建功能时，总是为其创建一个工作流。 +- 创建工作流时，总是为其创建一个步骤。 +- 在工作流中，对任何数据转换使用 `transform`。 +- 在工作流中，使用 `when` 来定义条件。 +- 调用步骤时不要使用 `await`。 +- 在工作流中，不要将工作流函数设为异步。 +- 不要为补偿函数的输入添加类型。 +- 在工作流中只使用步骤。 + +## 数据模型规则 + +- 使用 `@medusajs/framework/utils` 中的 `model` 实用程序来定义数据模型。 +- 数据模型变量应为驼峰式 (camelCase)。传递给 `model.define` 的数据模型名称应为蛇形 (snake_case)。 +- 向数据模型添加 `id` 字段时，总是使用 `.primaryKey()` 将其设为主键。 +- 一个数据模型只能有一个 `id`，其他 ID 应为 `text` 类型。 +- 数据模型字段应为蛇形 (snake_case)。 + +## 服务规则 + +- 创建服务时，总是将方法设为异步。 +- 如果模块有数据模型，则让服务扩展 `MedusaService`。 + +## 管理后台定制规则 + +- 在管理后台定制中发送请求时，总是使用 Medusa 的 JS SDK。 +- 使用 TailwindCSS 进行样式设计。 + +# 额外资源 + +- [Medusa 文档](https://docs.medusajs.com/llms-full.txt) diff --git a/rules-new/nativescript.mdc b/rules-new/nativescript.mdc new file mode 100644 index 0000000..17df9f9 --- /dev/null +++ b/rules-new/nativescript.mdc @@ -0,0 +1,42 @@ +--- +description: NativeScript 移动应用的最佳实践和模式 +globs: **/*.tsx, **/*.ts, **/*.vue, **/*.svelte, src/**/*.ts, app/**/*.ts, src/**/*.tsx, app/**/*.tsx, src/**/*.vue, app/**/*.vue, src/**/*.svelte +--- + +# NativeScript 最佳实践 + +## 代码风格与结构 +- 使用模块化组件和服务来组织代码，以提高可维护性。 +- 当平台特定代码超过 20 行时，使用平台特定文件（`.ios.ts`, `.android.ts`）。 +- 创建自定义原生代码时，使用类似 `custom-native/index.ios.ts`, `custom-native/index.android.ts`, `custom-native/common.ts`, `custom-native/index.d.ts` 的文件夹结构，以保持平台特定代码的组织性，并便于在其他地方通过单次导入使用，将 `custom-native` 替换为自定义代码的名称。 + +## 命名约定 +- 为平台特定的变量添加 `ios` 或 `android` 前缀（例如 `iosButtonStyle`）。 +- 使用描述性的名称为自定义组件和样式命名（`primaryButtonStyle`, `userProfileView`）。 + +## 用法 +- 在需要时，使用 `@NativeClass()` 扩展原生类。 +- 对于 iOS，在扩展原生类时，如果需要或使用委托，请始终使用 `static ObjCProtocols = [AnyUIKitDelegate];` 来声明自定义委托。 +- 对于 iOS，始终保留自定义委托实例以防止垃圾回收。例如，`let delegate = MyCustomDelegate.new() as MyCustomDelegate`，并确保它在类作用域内被保留。 +- 优先使用 `__ANDROID__` 和 `__APPLE__` 进行带摇树优化（tree-shaking）的条件平台代码。 +- 跟踪并清理所有计时器（`setTimeout`, `setInterval`）以避免内存泄漏。 + +## UI 和样式 +- 始终使用 TailwindCSS 作为 CSS 框架，使用 `"@nativescript/tailwind": "^2.1.0"` 与 `"tailwindcss": "~3.4.0"` 配对以实现一致的样式。 +- 为平台特定样式添加 `ios:` 和 `android:` 样式变体，`addVariant('android', '.ns-android &')`, `addVariant('ios', '.ns-ios &')`。 +- `darkMode: ['class', '.ns-dark']` +- 利用 `GridLayout` 或 `StackLayout` 实现灵活、响应式的布局。对于复杂布局，更强调正确使用 `GridLayout`，但对于更简单的线性排列，则使用 `StackLayout`。 +- 对隐藏时不应影响布局的元素使用 `visibility: 'hidden'`。 + +## 性能优化 +- 尽量避免深度嵌套布局容器，而是明智地使用 `GridLayout` 来设置复杂布局。 +- 避免在运行时直接操作可视化树，以最小化渲染开销。 +- 使用 TinyPNG 等压缩工具优化图像，以减少内存和应用大小。 +- 在修改 `App_Resources` 或 `package.json` 中的文件后，清理项目（`ns clean`）。 + +## 关键约定 +- 重用组件和样式以避免重复。 +- 在 `ListView` 和 `RadListView` 中使用模板选择器（`itemTemplateSelector`）实现条件布局。 +- 最小化 UI 绑定或方法中的繁重计算。 +- 仅当使用纯 XML 绑定时，才使用 `Observable` 或 `ObservableArray` 属性来高效地反映状态变化。 +- 使用 Angular、React、Solid、Svelte 或 Vue 时，始终利用它们各自的状态管理、生命周期钩子、渲染优化和响应式绑定，以获得最佳性能。 diff --git a/rules-new/nextjs.mdc b/rules-new/nextjs.mdc new file mode 100644 index 0000000..2e9bff6 --- /dev/null +++ b/rules-new/nextjs.mdc @@ -0,0 +1,52 @@ +--- +description: Next.js 结合 TypeScript 和 Tailwind UI 的最佳实践 +globs: **/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx +--- + +# Next.js 最佳实践 + +## 项目结构 +- 使用 App Router 目录结构 +- 将特定于路由的组件放置在 `app` 目录中 +- 将共享组件放置在 `components` 目录中 +- 将实用程序和辅助函数放置在 `lib` 目录中 +- 目录使用小写字母和短横线（例如 `components/auth-wizard`） + +## 组件 +- 默认使用服务器组件 (Server Components) +- 使用 'use client' 明确标记客户端组件 +- 将客户端组件包裹在带有名为 `fallback` 的 Suspense 中 +- 对非关键组件使用动态加载 +- 实现正确的错误边界 (Error Boundaries) +- 将静态内容和接口放在文件末尾 + +## 性能 +- 优化图片：使用 WebP 格式、尺寸数据、懒加载 +- 最小化 'useEffect' 和 'setState' 的使用 +- 尽可能优先使用服务器组件 (RSC) +- 对非关键组件使用动态加载 +- 实现正确的缓存策略 + +## 数据获取 +- 尽可能使用服务器组件进行数据获取 +- 实现正确的数据获取错误处理 +- 使用适当的缓存策略 +- 适当地处理加载和错误状态 + +## 路由 +- 使用 App Router 的约定 +- 为路由实现正确的加载和错误状态 +- 适当地使用动态路由 +- 需要时处理并行路由 + +## 表单和验证 +- 使用 Zod 进行表单验证 +- 实现正确的服务器端验证 +- 适当地处理表单错误 +- 在表单提交期间显示加载状态 + +## 状态管理 +- 最小化客户端状态 +- 谨慎使用 React Context +- 尽可能优先使用服务器状态 +- 实现正确的加载状态 diff --git a/rules-new/node-express.mdc b/rules-new/node-express.mdc new file mode 100644 index 0000000..c885c24 --- /dev/null +++ b/rules-new/node-express.mdc @@ -0,0 +1,86 @@ +--- +description: Node.js 和 Express.js 后端开发最佳实践 +globs: **/*.js, **/*.ts, src/**/*.ts +--- + +# Node.js 和 Express.js 最佳实践 + +## 项目结构 +- 使用正确的目录结构 +- 实现正确的模块组织 +- 使用正确的中间件组织 +- 按域组织路由 +- 实现正确的错误处理 +- 使用正确的配置管理 + +## Express 设置 +- 使用正确的中间件设置 +- 实现正确的路由 +- 使用正确的错误处理 +- 配置正确的安全中间件 +- 实现正确的验证 +- 使用正确的静态文件服务 + +## API 设计 +- 使用正确的 REST 原则 +- 实现正确的版本控制 +- 使用正确的请求验证 +- 正确处理错误 +- 实现正确的响应格式 +- 正确地为 API 编写文档 + +## 数据库集成 +- 使用正确的 ORM/ODM +- 实现正确的迁移 +- 使用正确的连接池 +- 实现正确的事务 +- 使用正确的查询优化 +- 正确处理数据库错误 + +## 认证 +- 实现正确的 JWT 处理 +- 使用正确的密码哈希 +- 实现正确的会话管理 +- 使用正确的 OAuth 集成 +- 实现正确的基于角色的访问控制 +- 正确处理认证错误 + +## 安全 +- 使用正确的 CORS 设置 +- 实现正确的速率限制 +- 使用正确的安全头 +- 实现正确的输入验证 +- 使用正确的加密 +- 处理安全漏洞 + +## 性能 +- 使用正确的缓存 +- 实现正确的异步操作 +- 使用正确的连接池 +- 实现正确的日志记录 +- 使用正确的监控 +- 正确处理高流量 + +## 测试 +- 编写正确的单元测试 +- 实现正确的集成测试 +- 使用正确的测试运行器 +- 实现正确的模拟 +- 测试错误场景 +- 使用正确的测试覆盖率 + +## 部署 +- 使用正确的 Docker 设置 +- 实现正确的 CI/CD +- 使用正确的环境变量 +- 配置正确的日志记录 +- 实现正确的监控 +- 处理部署错误 + +## 最佳实践 +- 遵循 Node.js 最佳实践 +- 正确使用 async/await +- 实现正确的错误处理 +- 使用正确的日志记录 +- 正确处理进程信号 +- 正确地为代码编写文档 diff --git a/rules-new/python.mdc b/rules-new/python.mdc new file mode 100644 index 0000000..d73640c --- /dev/null +++ b/rules-new/python.mdc @@ -0,0 +1,120 @@ +--- +description: 使用 Flask 和 SQLite 的现代软件开发的 Python 最佳实践和模式 +globs: **/*.py, src/**/*.py, tests/**/*.py +--- + +# Python 最佳实践 + +## 项目结构 +- 使用 `src/your_package_name/` 的 src 布局 +- 将测试放在与 `src/` 并行的 `tests/` 目录中 +- 将配置保存在 `config/` 中或作为环境变量 +- 将需求存储在 `requirements.txt` 或 `pyproject.toml` 中 +- 将静态文件放在 `static/` 目录中 +- 对 Jinja2 模板使用 `templates/` + +## 代码风格 +- 遵循 Black 代码格式化 +- 使用 isort 进行导入排序 +- 遵循 PEP 8 命名约定： + - 函数和变量使用蛇形命名法 (snake_case) + - 类使用帕斯卡命名法 (PascalCase) + - 常量使用大写 (UPPER_CASE) +- 最大行长为 88 个字符 (Black 默认) +- 使用绝对导入而非相对导入 + +## 类型提示 +- 对所有函数参数和返回值使用类型提示 +- 从 `typing` 模块导入类型 +- 使用 `Optional[Type]` 而不是 `Type | None` +- 对泛型类型使用 `TypeVar` +- 在 `types.py` 中定义自定义类型 +- 对鸭子类型使用 `Protocol` + +## Flask 结构 +- 使用 Flask 工厂模式 +- 使用蓝图 (Blueprints) 组织路由 +- 使用 Flask-SQLAlchemy 进行数据库操作 +- 实现正确的错误处理器 +- 使用 Flask-Login 进行认证 +- 以适当的关注点分离来构建视图 + +## 数据库 +- 使用 SQLAlchemy ORM +- 使用 Alembic 实现数据库迁移 +- 使用正确的连接池 +- 在单独的模块中定义模型 +- 实现正确的关系 +- 使用正确的索引策略 + +## 认证 +- 使用 Flask-Login 进行会话管理 +- 使用 Flask-OAuth 实现 Google OAuth +- 使用 bcrypt 哈希密码 +- 使用正确的会话安全 +- 实现 CSRF 保护 +- 使用正确的基于角色的访问控制 + +## API 设计 +- 使用 Flask-RESTful 构建 REST API +- 实现正确的请求验证 +- 使用正确的 HTTP 状态码 +- 一致地处理错误 +- 使用正确的响应格式 +- 实现正确的速率限制 + +## 测试 +- 使用 pytest 进行测试 +- 为所有路由编写测试 +- 使用 pytest-cov 进行覆盖率检查 +- 实现正确的夹具 (fixtures) +- 使用 pytest-mock 进行正确的模拟 +- 测试所有错误场景 + +## 安全 +- 在生产环境中使用 HTTPS +- 实现正确的 CORS +- 清理所有用户输入 +- 使用正确的会话配置 +- 实现正确的日志记录 +- 遵循 OWASP 指南 + +## 性能 +- 使用 Flask-Caching 进行正确的缓存 +- 实现数据库查询优化 +- 使用正确的连接池 +- 实现正确的分页 +- 对繁重操作使用后台任务 +- 监控应用程序性能 + +## 错误处理 +- 创建自定义异常类 +- 使用正确的 try-except 块 +- 实现正确的日志记录 +- 返回正确的错误响应 +- 正确处理边界情况 +- 使用正确的错误消息 + +## 文档 +- 使用 Google 风格的文档字符串 +- 为所有公共 API 编写文档 +- 保持 README.md 更新 +- 使用正确的内联注释 +- 生成 API 文档 +- 记录环境设置 + +## 开发工作流 +- 使用虚拟环境 (venv) +- 实现 pre-commit 钩子 +- 使用正确的 Git 工作流 +- 遵循语义化版本控制 +- 使用正确的 CI/CD 实践 +- 实现正确的日志记录 + +## 依赖 +- 固定依赖版本 +- 对生产环境使用 requirements.txt +- 分离开发依赖 +- 使用正确的包版本 +- 定期更新依赖 +- 检查安全漏洞 diff --git a/rules-new/react.mdc b/rules-new/react.mdc new file mode 100644 index 0000000..15b5909 --- /dev/null +++ b/rules-new/react.mdc @@ -0,0 +1,78 @@ +--- +description: 适用于现代 Web 应用程序的 React 最佳实践和模式 +globs: **/*.tsx, **/*.jsx, components/**/* +--- + +# React 最佳实践 + +## 组件结构 +- 使用函数组件而非类组件 +- 保持组件小而专注 +- 将可重用逻辑提取到自定义钩子中 +- 使用组合而非继承 +- 使用 TypeScript 实现正确的 prop 类型 +- 将大型组件拆分为更小、更专注的组件 + +## 钩子 (Hooks) +- 遵循钩子规则 +- 对可重用逻辑使用自定义钩子 +- 保持钩子专注和简单 +- 在 useEffect 中使用适当的依赖数组 +- 需要时在 useEffect 中实现清理 +- 避免嵌套钩子 + +## 状态管理 +- 对本地组件状态使用 useState +- 对复杂状态逻辑实现 useReducer +- 对共享状态使用 Context API +- 使状态尽可能靠近其使用位置 +- 通过适当的状态管理避免 prop 钻取 +- 仅在必要时使用状态管理库 + +## 性能 +- 实现正确的记忆化 (useMemo, useCallback) +- 对昂贵的组件使用 React.memo +- 避免不必要的重新渲染 +- 实现正确的懒加载 +- 在列表中使用正确的 key prop +- 分析和优化渲染性能 + +## 表单 +- 对表单输入使用受控组件 +- 实现正确的表单验证 +- 正确处理表单提交状态 +- 显示适当的加载和错误状态 +- 对复杂表单使用表单库 +- 为表单实现正确的无障碍性 + +## 错误处理 +- 实现错误边界 (Error Boundaries) +- 正确处理异步错误 +- 显示用户友好的错误消息 +- 实现正确的后备 UI +- 适当地记录错误 +- 优雅地处理边界情况 + +## 测试 +- 为组件编写单元测试 +- 为复杂流程实现集成测试 +- 使用 React Testing Library +- 测试用户交互 +- 测试错误场景 +- 实现正确的模拟数据 + +## 无障碍性 (Accessibility) +- 使用语义化 HTML 元素 +- 实现正确的 ARIA 属性 +- 确保键盘导航 +- 使用屏幕阅读器进行测试 +- 处理焦点管理 +- 为图像提供正确的 alt 文本 + +## 代码组织 +- 将相关组件分组 +- 使用正确的文件命名约定 +- 实现正确的目录结构 +- 使样式靠近组件 +- 使用正确的导入/导出 +- 为复杂的组件逻辑编写文档 diff --git a/rules-new/svelte.mdc b/rules-new/svelte.mdc new file mode 100644 index 0000000..76b3c86 --- /dev/null +++ b/rules-new/svelte.mdc @@ -0,0 +1,86 @@ +--- +description: Svelte 现代 Web 应用的最佳实践和模式 +globs: **/*.svelte, src/**/*.ts, src/**/*.js +--- + +# Svelte 最佳实践 + +## 组件结构 +- 保持组件小而专注 +- 使用正确的 TypeScript 集成 +- 实现正确的 props 类型定义 +- 使用正确的事件派发 +- 保持标记干净易读 +- 使用正确的插槽 (slot) 实现 + +## 响应性 (Reactivity) +- 使用正确的响应式声明 +- 实现正确的存储 (stores) +- 使用正确的响应式语句 +- 正确处理派生值 +- 使用正确的生命周期函数 +- 实现正确的绑定 + +## 状态管理 +- 使用正确的 Svelte 存储 (stores) +- 保持存储模块化 +- 使用正确的派生存储 (derived stores) +- 实现正确的动作 (actions) +- 正确处理异步状态 +- 使用正确的存储订阅 + +## 性能 +- 使用正确的组件懒加载 +- 实现正确的过渡 (transitions) +- 使用正确的动画 (animations) +- 避免不必要的响应性 +- 使用正确的事件转发 +- 实现正确的 key 块 + +## 路由 +- 使用 SvelteKit 进行路由 +- 实现正确的布局 +- 使用正确的路由参数 +- 正确处理加载状态 +- 实现正确的错误页面 +- 使用正确的导航方法 + +## 表单 +- 使用正确的表单绑定 +- 实现正确的验证 +- 正确处理表单提交 +- 显示正确的加载状态 +- 使用正确的错误处理 +- 实现正确的表单重置 + +## TypeScript 集成 +- 使用正确的组件类型 +- 实现正确的 prop 类型 +- 使用正确的事件类型 +- 处理正确的类型推断 +- 使用正确的存储类型 +- 实现正确的动作类型 + +## 测试 +- 编写正确的单元测试 +- 实现正确的组件测试 +- 使用正确的测试库 +- 正确测试存储 +- 实现正确的模拟 (mocking) +- 测试异步操作 + +## 最佳实践 +- 遵循 Svelte 风格指南 +- 使用正确的命名约定 +- 保持组件井然有序 +- 实现正确的错误处理 +- 使用正确的事件处理 +- 为复杂逻辑编写文档 + +## 构建和工具 +- 使用 Vite 进行开发 +- 配置正确的构建设置 +- 使用正确的环境变量 +- 实现正确的代码分割 +- 使用正确的资产处理 +- 配置正确的优化 diff --git a/rules-new/tailwind.mdc b/rules-new/tailwind.mdc new file mode 100644 index 0000000..47f1bac --- /dev/null +++ b/rules-new/tailwind.mdc @@ -0,0 +1,78 @@ +--- +description: 适用于现代 Web 应用程序的 Tailwind CSS 和 UI 组件最佳实践 +globs: **/*.css, **/*.tsx, **/*.jsx, tailwind.config.js, tailwind.config.ts +--- + +# Tailwind CSS 最佳实践 + +## 项目设置 +- 使用正确的 Tailwind 配置 +- 正确配置主题扩展 +- 设置正确的清除 (purge) 配置 +- 使用正确的插件集成 +- 配置自定义间距和断点 +- 设置正确的调色板 + +## 组件样式 +- 使用功能类而非自定义 CSS +- 需要时使用 @apply 将相关功能类分组 +- 使用正确的响应式设计功能类 +- 正确实现深色模式 +- 使用正确的状态变体 +- 保持组件样式一致 + +## 布局 +- 有效使用 Flexbox 和 Grid 功能类 +- 实现正确的间距系统 +- 需要时使用容器查询 +- 实现正确的响应式断点 +- 使用正确的内边距和外边距功能类 +- 实现正确的对齐功能类 + +## 排版 +- 使用正确的字体大小功能类 +- 实现正确的行高 +- 使用正确的字体粗细功能类 +- 正确配置自定义字体 +- 使用正确的文本对齐 +- 实现正确的文本装饰 + +## 颜色 +- 使用语义化的颜色命名 +- 实现正确的颜色对比度 +- 有效使用不透明度功能类 +- 正确配置自定义颜色 +- 使用正确的渐变功能类 +- 实现正确的悬停状态 + +## 组件 +- 当可用时使用 shadcn/ui 组件 +- 正确扩展组件 +- 保持组件变体一致 +- 实现正确的动画 +- 使用正确的过渡功能类 +- 牢记无障碍性 + +## 响应式设计 +- 使用移动优先的方法 +- 实现正确的断点 +- 有效使用容器查询 +- 正确处理不同的屏幕尺寸 +- 实现正确的响应式排版 +- 使用正确的响应式间距 + +## 性能 +- 使用正确的清除 (purge) 配置 +- 最小化自定义 CSS +- 使用正确的缓存策略 +- 实现正确的代码分割 +- 为生产环境优化 +- 监控打包大小 + +## 最佳实践 +- 遵循命名约定 +- 保持样式井然有序 +- 使用正确的文档 +- 实现正确的测试 +- 遵循无障碍性指南 +- 使用正确的版本控制 diff --git a/rules-new/typescript.mdc b/rules-new/typescript.mdc new file mode 100644 index 0000000..99037d9 --- /dev/null +++ b/rules-new/typescript.mdc @@ -0,0 +1,57 @@ +--- +description: 适用于现代 Web 开发的 TypeScript 编码标准和最佳实践 +globs: **/*.ts, **/*.tsx, **/*.d.ts +--- + +# TypeScript 最佳实践 + +## 类型系统 +- 对象定义优先使用接口 (interfaces) 而不是类型 (types) +- 对联合、交叉和映射类型使用类型 (type) +- 避免使用 `any`，对未知类型优先使用 `unknown` +- 使用严格的 TypeScript 配置 +- 利用 TypeScript 的内置实用程序类型 +- 对可重用的类型模式使用泛型 + +## 命名约定 +- 类型名称和接口使用帕斯卡命名法 (PascalCase) +- 变量和函数使用驼峰命名法 (camelCase) +- 常量使用大写 (UPPER_CASE) +- 使用带辅助动词的描述性名称（例如 isLoading, hasError） +- React props 的接口以 'Props' 为前缀（例如 ButtonProps） + +## 代码组织 +- 将类型定义放在其使用位置附近 +- 当类型和接口共享时，从专用的类型文件中导出 +- 使用桶式导出 (index.ts) 来组织导出 +- 将共享类型放在 `types` 目录中 +- 将组件 props 与其组件放在一起 + +## 函数 +- 对公共函数使用显式返回类型 +- 对回调和方法使用箭头函数 +- 使用自定义错误类型实现正确的错误处理 +- 对复杂的类型场景使用函数重载 +- 优先使用 async/await 而不是 Promises + +## 最佳实践 +- 在 tsconfig.json 中启用严格模式 +- 对不可变属性使用 readonly +- 利用可辨识联合 (discriminated unions) 实现类型安全 +- 对运行时类型检查使用类型守卫 (type guards) +- 实现正确的 null 检查 +- 除非必要，否则避免类型断言 + +## 错误处理 +- 为领域特定的错误创建自定义错误类型 +- 对可能失败的操作使用 Result 类型 +- 实现正确的错误边界 +- 使用带类型化 catch 子句的 try-catch 块 +- 正确处理 Promise 拒绝 + +## 模式 +- 对复杂的对象创建使用构建器模式 (Builder pattern) +- 对数据访问实现仓库模式 (Repository pattern) +- 对对象创建使用工厂模式 (Factory pattern) +- 利用依赖注入 +- 对封装使用模块模式 (Module pattern) diff --git a/rules-new/vue.mdc b/rules-new/vue.mdc new file mode 100644 index 0000000..c0aa6eb --- /dev/null +++ b/rules-new/vue.mdc @@ -0,0 +1,86 @@ +--- +description: 适用于现代 Web 应用程序的 Vue.js 最佳实践和模式 +globs: **/*.vue, **/*.ts, components/**/* +--- + +# Vue.js 最佳实践 + +## 组件结构 +- 使用组合式 API (Composition API) 而非选项式 API (Options API) +- 保持组件小而专注 +- 使用正确的 TypeScript 集成 +- 实现正确的 props 验证 +- 使用正确的 emit 声明 +- 保持模板逻辑最小化 + +## 组合式 API +- 正确使用 ref 和 reactive +- 实现正确的生命周期钩子 +- 对可重用逻辑使用组合式函数 (composables) +- 保持 setup 函数整洁 +- 使用正确的计算属性 (computed properties) +- 实现正确的侦听器 (watchers) + +## 状态管理 +- 使用 Pinia 进行状态管理 +- 保持存储 (stores) 模块化 +- 使用正确的状态组合 +- 实现正确的 actions +- 使用正确的 getters +- 正确处理异步状态 + +## 性能 +- 使用正确的组件懒加载 +- 实现正确的缓存 +- 使用正确的计算属性 +- 避免不必要的侦听器 +- 正确使用 v-show 与 v-if +- 实现正确的 key 管理 + +## 路由 +- 正确使用 Vue Router +- 实现正确的导航守卫 +- 使用正确的路由元字段 (meta fields) +- 正确处理路由参数 +- 实现正确的懒加载 +- 使用正确的导航方法 + +## 表单 +- 正确使用 v-model +- 实现正确的验证 +- 正确处理表单提交 +- 显示正确的加载状态 +- 使用正确的错误处理 +- 实现正确的表单重置 + +## TypeScript 集成 +- 使用正确的组件类型定义 +- 实现正确的 prop 类型 +- 使用正确的 emit 声明 +- 处理正确的类型推断 +- 使用正确的组合式函数类型 +- 实现正确的存储类型 + +## 测试 +- 编写正确的单元测试 +- 实现正确的组件测试 +- 正确使用 Vue Test Utils +- 正确测试组合式函数 +- 实现正确的模拟 (mocking) +- 测试异步操作 + +## 最佳实践 +- 遵循 Vue 风格指南 +- 使用正确的命名约定 +- 保持组件井然有序 +- 实现正确的错误处理 +- 使用正确的事件处理 +- 为复杂逻辑编写文档 + +## 构建和工具 +- 使用 Vite 进行开发 +- 配置正确的构建设置 +- 使用正确的环境变量 +- 实现正确的代码分割 +- 使用正确的资产处理 +- 配置正确的优化 diff --git a/rules/code-guidelines-cursorrules-prompt-file/README.md b/rules/code-guidelines-cursorrules-prompt-file/README.md new file mode 100644 index 0000000..f7b0c27 --- /dev/null +++ b/rules/code-guidelines-cursorrules-prompt-file/README.md @@ -0,0 +1,15 @@ +# 代码指南 .cursorrules 提示文件 + +作者：Hamza Farhan + +## 你可以构建什么 +代码分析工具：开发一个工具，用于分析代码是否符合 .cursorrules AI 文件中设置的规则。它会高亮显示违规行为，例如缺失错误处理、缺少测试覆盖以及不匹配的编码风格。自动重构服务：创建一个服务，该服务可以逐个文件地自动重构代码，同时遵守诸如无空白建议、避免魔术数字和确保模块化设计等准则。项目一致性检查器：构建一个工具，用于检查项目中多个文件的一致编码风格、性能优先级和安全考虑，同时避免不必要的更新。开发者助手扩展：设计一个浏览器或 IDE 扩展，提供对代码编辑的实时反馈，强调明确的变量名、避免道歉，并确保不需要不必要的确认。代码优化平台：建立一个平台，提出性能改进和模块化设计策略的建议，同时确保版本兼容性并优先考虑安全第一的方法。单元测试建议应用：创建一个应用，为新的或修改过的代码自动生成单元测试，强调覆盖率，除非被要求，否则不显示或讨论当前实现。版本兼容性分析器：开发一个分析器，检查代码更改是否与项目指定的语言或框架版本兼容，以确保顺利集成和功能正常。边界情况识别器：构建一个工具，扫描代码以识别潜在的边界情况并提出处理策略，确保稳健的错误处理和日志记录。上下文感知代码审查器：创建一个代码审查平台，使用上下文生成的文件来提供对编辑的反馈，确保没有不必要的确认和文件保留。模块化设计教育平台：开发一个学习平台，教育开发人员实施和鼓励模块化设计原则，重点关注代码的可重用性和可维护性。断言验证器：构建一个集成到 CI/CD 管道中的服务，用于检查代码中断言的存在和正确使用，从而提高验证准确性和早期错误检测。硬编码值检测器：创建一个工具，扫描代码库以查找魔术数字，并建议替换为命名常量，从而提高清晰度和可维护性。错误处理增强器：设计一个插件或独立工具，为代码中的错误处理机制提出改进建议，为稳健的日志记录实践提供建议。 + +## 优点 + + +## 概要 +在协作项目中工作的开发人员将通过建立清晰高效的代码审查和更新实践而受益，确保整个团队的代码质量一致、安全且可维护。 + +## .cursorrules 提示概述 +.cursorrules 文件概述了在编辑或建议代码更改时要遵循的一系列规则和准则。它强调验证信息、逐个文件进行更改、保留现有代码以及避免不必要的确认或更新。它建议不要使用道歉、不必要的空白更改或总结所做的更改。重点是确保提供真实的文件链接、使用明确的变量名以及遵循一致的编码风格。性能、安全性、错误处理、模块化设计、版本兼容性、边界情况和测试覆盖率是优先考虑的。该文件不鼓励使用“魔术数字”，并鼓励使用断言来及早发现错误。 diff --git a/rules/code-guidelines-cursorrules-prompt-file/general-coding-rules.mdc b/rules/code-guidelines-cursorrules-prompt-file/general-coding-rules.mdc new file mode 100644 index 0000000..1a635c0 --- /dev/null +++ b/rules/code-guidelines-cursorrules-prompt-file/general-coding-rules.mdc @@ -0,0 +1,30 @@ +--- +description: 在所有文件类型中应用通用编码规则，以保持代码质量、一致性并防止常见错误。 +globs: **/*.* +--- +- 在呈现信息之前，务必核实信息。不要在没有明确证据的情况下做出假设或推测。 +- 逐个文件进行更改，给我一个发现错误的机会。 +- 切勿使用道歉。 +- 避免在评论或文档中提供关于理解的反馈。 +- 不要建议修改空白字符。 +- 不要总结所做的更改。 +- 除了明确要求的内容外，不要虚构其他更改。 +- 不要请求确认上下文中已提供的信息。 +- 不要删除不相关的代码或功能。注意保留现有结构。 +- 将所有编辑内容放在一个代码块中提供，而不是为同一个文件提供多步骤的指令或解释。 +- 不要要求用户验证在提供的上下文中可见的实现。 +- 当没有实际需要修改时，不要建议更新或更改文件。 +- 始终提供指向真实文件的链接，而不是上下文生成的文件。 +- 除非特别要求，否则不要显示或讨论当前的实现。 +- 记住检查上下文生成的文件以获取当前文件的内容和实现。 +- 优先使用描述性、明确的变量名，而不是简短、模糊的变量名，以增强代码的可读性。 +- 遵守项目中现有的编码风格以保持一致性。 +- 在建议更改时，在适用的情况下考虑并优先考虑代码性能。 +- 在修改或建议代码更改时，始终考虑安全影响。 +- 为新的或修改过的代码建议或包含适当的单元测试。 +- 在必要时实现稳健的错误处理和日志记录。 +- 鼓励模块化设计原则，以提高代码的可维护性和可重用性。 +- 确保建议的更改与项目指定的语言或框架版本兼容。 +- 用命名常量替换硬编码的值，以提高代码的清晰度和可维护性。 +- 在实现逻辑时，始终考虑并处理潜在的边界情况。 +- 尽可能包含断言，以验证假设并及早发现潜在错误。 diff --git a/rules/code-pair-interviews/README.md b/rules/code-pair-interviews/README.md new file mode 100644 index 0000000..15ba4d0 --- /dev/null +++ b/rules/code-pair-interviews/README.md @@ -0,0 +1,30 @@ +# Cursor AI 结对编程面试 .cursorrules 提示文件 + +作者：Radamés Roriz + +## 你可以构建什么 + +这个 .cursorrules 文件旨在指导 Cursor AI 生成符合结对编程面试中常见的代码结构和风格最佳实践与期望的代码。它强调干净、可维护和专业质量的代码，以及协作编码实践。 + +## 优点 + +- **提高代码质量：** 确保生成的代码结构良好、可读性强，并遵循行业标准的风格约定。 +- **面试准备：** 通过模拟预期的编码环境和标准，帮助练习和准备结对编程面试。 +- **有效协作：** 促进在协作环境中易于理解和使用的代码。 +- **减少错误：** 鼓励生成考虑边界情况并包含基本错误处理的代码。 +- **一致性：** 在生成的代码中保持一致的编码风格，反映专业的软件开发实践。 + +## 概要 + +.cursorrules 文件为 Cursor AI 提供了关于以下方面的详细说明： + +- **代码结构与组织：** 如何分解问题，将代码组织成模块化单元，以及选择合适的数据结构和算法。 +- **编码风格：** 关于缩进、命名约定、注释、行长和代码布局的指南。 +- **协作与沟通：** 大声思考、给予/接受反馈以及协作调试的实践。 +- **编码最佳实践：** 强调编写干净代码、处理边界情况和时间管理。 +- **风格指南：** 参考 Python 的 PEP 8 和代码风格的一般原则。 +- **要避免的陷阱：** 结对编程面试中的常见错误以及如何预防它们。 + +## .cursorrules 提示概述 + +这个 .cursorrules 提示文件作为 Cursor AI 的综合指南，用于生成能够反映结对编程面试中预期的质量和协作方法的代码。它不仅涵盖了编写正确代码的技术方面，还包括了代码清晰度、风格一致性和有效沟通等关键要素，这些对于在此类评估中取得成功至关重要。通过遵守这些规则，Cursor AI 可以生成能够证明候选人已为实际软件开发和协作编码环境做好准备的代码。 diff --git a/rules/code-style-consistency-cursorrules-prompt-file/README.md b/rules/code-style-consistency-cursorrules-prompt-file/README.md new file mode 100644 index 0000000..b97226b --- /dev/null +++ b/rules/code-style-consistency-cursorrules-prompt-file/README.md @@ -0,0 +1,37 @@ +# 代码风格一致性提示 + +作者：Peter M Souza Jr + +一个专门的 .cursorrules 提示，用于分析代码库模式，并确保新生成的 AI 代码遵循项目的既定风格和约定。 + +## 你可以构建什么 + +- **风格分析报告**：详细描述现有代码库的命名约定、格式化和架构模式的综合配置文件。 +- **一致的功能实现**：与现有代码风格无缝集成的新功能。 +- **自适应重构**：在保持风格完整性的前提下更新现有代码。 +- **风格自适应中间件**：一个处理层，可将任意代码转换为匹配项目模式。 +- **架构模式检测器**：识别和分类代码库中结构模式的工具。 + +## 优点 + +- **无缝集成**：生成的代码与现有项目代码自然融合。 +- **团队对齐**：确保 AI 辅助符合团队标准，无需额外返工。 +- **减少认知负荷**：一致的代码更易于阅读、理解和维护。 +- **改善协作**：最大限度地减少代码审查和合并中基于风格的冲突。 +- **渐进式增强**：适应代码库中不断发展的模式。 +- **上下文感知辅助**：尊重项目特定约定的 AI 建议。 + +## 概要 + +此提示可作为任何代码生成任务的强大前缀，在生成新代码之前分析项目的现有风格模式，以使其与既定约定和谐集成。 + +## .cursorrules 提示概述 + +.cursorrules 提示通过以下关键要素指导开发人员保持代码风格一致性： + +- **风格分析框架**：用于检查和分类代码模式的综合方法论。 +- **风格配置文件模板**：用于记录已识别约定的结构化格式。 +- **实践示例**：基于风格分析进行代码自适应的演示。 +- **一致性最佳实践**：保持风格完整性的十个关键原则。 +- **文件分析策略**：选择代表性文件以建立模式的指南。 +- **自适应技术**：将代码转换为匹配现有模式的具体方法。 diff --git a/rules/convex-cursorrules-prompt-file/convex-development---general.mdc b/rules/convex-cursorrules-prompt-file/convex-development---general.mdc new file mode 100644 index 0000000..0f5e285 --- /dev/null +++ b/rules/convex-cursorrules-prompt-file/convex-development---general.mdc @@ -0,0 +1,7 @@ +--- +description: 应用于 Convex 开发的通用规则，强调模式设计、验证器使用和系统字段的正确处理。 +globs: **/convex/**/*.* +--- +- 在使用 Convex 时，优先使用 `v` 验证器来正确定义模式。 +- 注意自动生成的系统字段 `_id` 和 `_creationTime`。 +- 有关可用类型，请参阅 https://docs.convex.dev/database/types。 diff --git a/rules/convex-cursorrules-prompt-file/convex-schema-design---built-in-types.mdc b/rules/convex-cursorrules-prompt-file/convex-schema-design---built-in-types.mdc new file mode 100644 index 0000000..e776bbe --- /dev/null +++ b/rules/convex-cursorrules-prompt-file/convex-schema-design---built-in-types.mdc @@ -0,0 +1,6 @@ +--- +description: 提供在使用内置系统字段和数据类型定义 Convex 模式时的指导，以确保正确处理数据。 +globs: **/convex/schema.ts +--- +- 在设计模式时，请参考 https://docs.convex.dev/database/types 提供的系统内置字段和数据类型。 +- 特别注意 `v` 验证器构建器 (https://docs.convex.dev/api/modules/values#v) 在定义模式类型时的正确用法。 diff --git a/translation_helper.py b/translation_helper.py new file mode 100644 index 0000000..7a0afa2 --- /dev/null +++ b/translation_helper.py @@ -0,0 +1,105 @@ +import os +import re + +# --- 配置 --- +# 脚本会自动计算路径，通常无需修改 +ORIGINAL_PROJECT_PATH = os.path.abspath(os.path.join('..', 'awesome-cursorrules')) +TRANSLATED_PROJECT_PATH = os.path.abspath('.') +PLAN_FILE_PATH = os.path.join(TRANSLATED_PROJECT_PATH, 'plan.md') + +# --- 翻译模型使用的 Prompt 模板 --- +PROMPT_TEMPLATE = """ +# 任务：将以下 Markdown 内容翻译为简体中文 + +请严格遵守以下规则： +1. **保留格式**：完整保留所有 Markdown 格式（标题、列表、链接、粗体等）。 +2. **代码不变**：代码块 (```) 和行内代码 (`) `内的所有内容（包括注释）保持原样，绝不翻译。 +3. **术语准确**：使用行业公认的技术术语。 +4. **流畅自然**：译文需通顺易懂。 + +--- +**英文原文:** +```markdown +{file_content} +``` +--- +**简体中文译文:** +""" + +def get_untranslated_files(): + """从 plan.md 读取未翻译的文件列表""" + untranslated = [] + # 正则表达式，用于匹配未完成的条目，例如：- [ ] `rules/cloud-native/README.md` + pattern = re.compile(r'-\s*\[\s*\]\s*`([^`]+)`') + try: + with open(PLAN_FILE_PATH, 'r', encoding='utf-8') as f: + for line in f: + match = pattern.search(line) + if match: + untranslated.append(match.group(1).replace('/', '\\')) # 适配 Windows 路径 + except FileNotFoundError: + print(f"错误：找不到计划文件 '{PLAN_FILE_PATH}'") + return None + return untranslated + +def main(): + """主执行函数""" + print("--- 开始批量翻译任务 ---") + + files_to_translate = get_untranslated_files() + + if files_to_translate is None: + return + + if not files_to_translate: + print("太棒了！plan.md 中的所有文件都已标记为完成。") + return + + print(f"在 plan.md 中找到 {len(files_to_translate)} 个待翻译文件。") + print("-" * 20) + + for i, relative_path in enumerate(files_to_translate, 1): + print(f"\n--- 任务 {i}/{len(files_to_translate)} ---") + print(f"文件: {relative_path}") + + source_path = os.path.join(ORIGINAL_PROJECT_PATH, relative_path) + dest_path = os.path.join(TRANSLATED_PROJECT_PATH, relative_path) + + # 1. 读取源文件 + try: + with open(source_path, 'r', encoding='utf-8') as f: + content = f.read() + except FileNotFoundError: + print(f" [错误] 找不到源文件: {source_path}") + print(" 请按 Enter 键跳过此文件...") + input() + continue + except Exception as e: + print(f" [错误] 读取源文件时出错: {e}") + print(" 请按 Enter 键跳过此文件...") + input() + continue + + # 2. 生成 Prompt + full_prompt = PROMPT_TEMPLATE.format(file_content=content) + + # 3. 输出操作指令 + print("\n [操作 1/3] 请复制下面的完整 Prompt，并将其输入到您的翻译模型中：") + print("-" * 10 + " PROMPT 开始 " + "-" * 10) + print(full_prompt) + print("-" * 10 + " PROMPT 结束 " + "-" * 10) + + print(f"\n [操作 2/3] 将翻译模型生成的中文内容保存到以下路径（如果目录不存在，请先创建）：") + print(f" 目标文件路径: {dest_path}") + + print("\n [操作 3/3] 保存文件后，请按 Enter 键继续处理下一个文件...") + + # 等待用户确认 + input() + + print("\n--- 所有任务已处理完毕 ---") + print("请记得更新 plan.md，将所有完成的任务标记为 [x]。") + + +if __name__ == "__main__": + main() From 03832679498a14177c847f21d24c179efe67a1a1 Mon Sep 17 00:00:00 2001 From: None Date: Wed, 2 Jul 2025 22:10:45 +0800 Subject: [PATCH 08/19] =?UTF-8?q?=F0=9F=93=9D=20docs(rules):=20=E5=AE=8C?= =?UTF-8?q?=E6=88=90=E5=85=A8=E9=83=A8rules=E6=96=87=E6=A1=A3=E7=9A=84?= =?UTF-8?q?=E7=BF=BB=E8=AF=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 17 ++ CONTRIBUTING.md | 7 + PROJECT_TODO.md | 66 -------- README.md | 30 +--- docs/translation-progress.md | 48 +++--- plan.md | 46 ------ .../.cursorrules | 81 +++++---- .../admin-interface-rule.mdc | 30 +++- .../entry-creation-rule.mdc | 37 ++++- .../frontend-tech-stack.mdc | 39 ++++- .../payment-tracking-rule.mdc | 31 +++- .../request-and-entry-tracking-rule.mdc | 33 +++- .../request-limit-rule.mdc | 38 ++++- .../state-transition-rule.mdc | 36 +++- .../strategic-planning-with-pseudocode.mdc | 56 ++++++- .../strict-user-requirements-adherence.mdc | 37 ++++- .../submission-process-outline.mdc | 45 ++++- .../weekly-scoring-process-pseudocode.mdc | 81 ++++++++- .../readme-md-guidelines.mdc | 86 +++++++++- .../fastapi-dependency-injection.mdc | 88 +++++++++- .../fastapi-file-structure.mdc | 96 ++++++++++- .../fastapi-performance-metrics.mdc | 41 ++++- .../fastapi-startup-and-shutdown-events.mdc | 102 +++++++++++- .../convex-schema-design---example-schema.mdc | 6 + .../convex-schema-design---system-fields.mdc | 6 + .../database-algorithm-rules.mdc | 49 +++++- .../dragonruby-error-handling.mdc | 6 + .../dragonruby-general-ruby-rules.mdc | 9 + .../dragonruby-naming-conventions.mdc | 7 + .../dragonruby-syntax-and-formatting.mdc | 7 + .../README.md | 41 +++++ .../README.md | 37 +++++ .../commit-message-format.mdc | 22 +++ .../README.md | 35 ++++ .../.cursorrules | 37 ++--- .../README.md | 37 ++++- .../angular-general.mdc | 38 ++--- .../angular-template-hints.mdc | 6 +- .../general-reasoning.mdc | 10 +- .../refactoring-existing-code.mdc | 6 +- .../typescript-coding-style.mdc | 12 +- .../solidjs---complex-state-management.mdc | 155 +++++++++++++++++- ...lidjs---conditional-and-list-rendering.mdc | 142 +++++++++++++++- .../solidjs---data-fetching.mdc | 144 +++++++++++++++- .../solidjs---derived-values-management.mdc | 107 +++++++++++- .../solidjs---error-boundaries.mdc | 93 ++++++++++- ...djs---functional-components-preference.mdc | 87 +++++++++- .../solidjs---jsx-templates.mdc | 121 +++++++++++++- .../solidjs---lazy-loading.mdc | 116 ++++++++++++- .../solidjs---naming-conventions.mdc | 66 +++++++- .../solidjs---optimization-features.mdc | 113 ++++++++++++- .../solidjs---reactive-state-management.mdc | 93 ++++++++++- .../README.md | 36 ++++ .../README.md | 13 ++ .../file-by-file-changes-rule.mdc | 5 + .../README.md | 35 ++++ 56 files changed, 2553 insertions(+), 315 deletions(-) delete mode 100644 PROJECT_TODO.md delete mode 100644 plan.md create mode 100644 rules/convex-cursorrules-prompt-file/convex-schema-design---example-schema.mdc create mode 100644 rules/convex-cursorrules-prompt-file/convex-schema-design---system-fields.mdc create mode 100644 rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-error-handling.mdc create mode 100644 rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-general-ruby-rules.mdc create mode 100644 rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-naming-conventions.mdc create mode 100644 rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-syntax-and-formatting.mdc create mode 100644 rules/drupal-11-cursorrules-prompt-file/README.md create mode 100644 rules/elixir-engineer-guidelines-cursorrules-prompt-file/README.md create mode 100644 rules/elixir-engineer-guidelines-cursorrules-prompt-file/commit-message-format.mdc create mode 100644 rules/engineering-ticket-template-cursorrules-prompt-file/README.md create mode 100644 rules/gherkin-style-testing-cursorrules-prompt-file/README.md create mode 100644 rules/git-conventional-commit-messages/README.md create mode 100644 rules/github-code-quality-cursorrules-prompt-file/file-by-file-changes-rule.mdc create mode 100644 rules/xray-test-case-cursorrules-prompt-file/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 99acddf..f94c8d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,23 @@ 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， 并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 +## [1.4.0] - 2025-07-02 + +### 新增 +- 完成所有规则集翻译 +- 更新文档反映最新进度 + +## [1.3.0] - 2025-07-02 + +### 翻译更新 +- 完成 Elixir 工程师指南翻译 +- 完成工程工单模板翻译 +- 完成 Gherkin 风格测试翻译 +- 完成 Git 约定式提交消息翻译 +- 完成 GitHub 代码质量翻译 +- 完成 Xray 测试用例翻译 +- 更新翻译进度文档 + ## [1.2.0] - 2025-07-02 ### 文档更新 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 35fb37e..e7413fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -201,6 +201,13 @@ refactor: improve project structure - **Pull Request**：提交代码和翻译 - **Discussions**：参与项目讨论 +## 维护阶段贡献指南 + +本项目翻译已全部完成，欢迎参与维护工作： +- 报告问题 +- 提交改进建议 +- 帮助同步上游更新 + --- **感谢您的贡献！每一个翻译都让中文开发者社区受益。** 🙏 diff --git a/PROJECT_TODO.md b/PROJECT_TODO.md deleted file mode 100644 index 832c398..0000000 --- a/PROJECT_TODO.md +++ /dev/null @@ -1,66 +0,0 @@ -# 项目待办事项清单 📋 - -> Awesome Cursor Rules 中文版项目发展规划和任务清单 - -## 📊 项目概览 - -### 当前状态 (v1.0.1) -- ✅ **已完成翻译**: 约 30-40 个核心规则集 -- ✅ **项目结构**: 优化的分类目录，便于查找 -- ✅ **文档体系**: 包含 `README.md`, `CHANGELOG.md`, `CODE_OF_CONDUCT.md` -- ❌ **待办任务**: 大量来自原项目的规则集尚未翻译 - -### 项目目标 -- 🎯 **翻译扩展**: 逐步覆盖原项目中所有高质量、高热度的规则集。 -- 🎯 **社区建设**: 吸引更多开发者参与翻译、校对和贡献。 -- 🎯 **质量提升**: 建立 PR 审核和反馈机制，确保翻译质量。 - ---- - -## 🔥 翻译优先级任务 - -为了让项目尽快覆盖主流技术栈，我们设定了以下优先级。欢迎社区开发者认领任务！ - -### 优先级最高：核心后端 & 前端框架 (近期目标) -* [ ] **Python 生态** - * [x] `python-fastapi-best-practices-cursorrules-prompt-f` (FastAPI 最佳实践) - * [x] `python-django-best-practices-cursorrules-prompt-fi` (Django 最佳实践) - * [x] `cursorrules-file-cursor-ai-python-fastapi-api` (FastAPI API 示例) - * [x] `python-flask-json-guide-cursorrules-prompt-file` (Flask 指南) -* [ ] **前端框架 (Vue 之外)** - * [x] `angular-typescript-cursorrules-prompt-file` (Angular & TypeScript) - * [x] `sveltekit-tailwindcss-typescript-cursorrules-promp` (SvelteKit & Tailwind) - * [x] `solidjs-basic-cursorrules-prompt-file` (SolidJS 基础) -* [x] **Node.js 生态** - * [x] `nodejs-mongodb-jwt-express-react-cursorrules-promp` (Node.js & Express & MongoDB) - * [x] `es-module-nodejs-guidelines-cursorrules-prompt-fil` (Node.js ES Module 指南) -* [x] **其他后端** - * [x] `laravel-php-83-cursorrules-prompt-file` (PHP & Laravel) - * [x] `kotlin-springboot-best-practices-cursorrules-prompt-file` (Kotlin & SpringBoot) - * [x] `elixir-phoenix-docker-setup-cursorrules-prompt-fil` (Elixir & Phoenix) - -### 优先级中：移动端 & DevOps & 测试 -* [x] **移动开发** - * [x] `android-jetpack-compose-cursorrules-prompt-file` (Android Jetpack Compose) - * [x] `flutter-app-expert-cursorrules-prompt-file` (Flutter 专家指南) - * [x] `swiftui-guidelines-cursorrules-prompt-file` (SwiftUI 指南) - * [x] `react-native-expo-cursorrules-prompt-file` (React Native & Expo) -* [ ] **DevOps & 平台** - * [ ] `github-code-quality-cursorrules-prompt-file` (GitHub 代码质量) - * [ ] `python-containerization-cursorrules-prompt-file` (Python 容器化) - * [ ] `kubernetes-mkdocs-documentation-cursorrules-prompt` (Kubernetes & MkDocs) -* [ ] **测试** - * [ ] `cypress-e2e-testing-cursorrules-prompt-file` (Cypress E2E 测试) - * [ ] `playwright-e2e-testing-cursorrules-prompt-file` (Playwright E2E 测试) - * [ ] `jest-unit-testing-cursorrules-prompt-file` (Jest 单元测试) - ---- - -## 🚀 如何贡献 - -1. **选择任务**: 从上面的列表中选择一个你感兴趣的未勾选任务。 -2. **创建 Issue**: 在项目的 "Issues" 页面创建一个新的 Issue，标题为 `[翻译任务] <规则集名称>`，例如 `[翻译任务] python-django-best-practices`，并将自己分配给该 Issue。 -3. **开始翻译**: Fork 本项目，在你的分支上完成翻译工作。 -4. **提交 PR**: 完成后，提交一个 Pull Request 到主分支，并在描述中链接到你创建的 Issue。 - -我们期待你的贡献！ diff --git a/README.md b/README.md index 3bac6ea..11757c3 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,14 @@
    -[![项目状态](https://img.shields.io/badge/status-active-success?style=for-the-badge)](https://github.com/LessUp/awesome-cursorrules-zh) +[![项目状态](https://img.shields.io/badge/status-translating-yellow?style=for-the-badge)](https://github.com/LessUp/awesome-cursorrules-zh) +[![翻译进度](https://img.shields.io/badge/progress-92.6%25-brightgreen?style=for-the-badge)](./docs/translation-progress.md) [![GitHub Stars](https://img.shields.io/github/stars/LessUp/awesome-cursorrules-zh?style=for-the-badge&logo=github&label=Stars)](https://github.com/LessUp/awesome-cursorrules-zh/stargazers) [![Fork](https://img.shields.io/github/forks/LessUp/awesome-cursorrules-zh?style=for-the-badge&logo=github&label=Fork)](https://github.com/LessUp/awesome-cursorrules-zh/network/members) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](./LICENSE) [![贡献指南](https://img.shields.io/badge/Contributing-Welcome-brightgreen.svg?style=for-the-badge)](./CONTRIBUTING.md) -**一个由社区驱动、为中文开发者量身打造的 `Awesome Cursor Rules` 高质量翻译和优化项目。** +**一个由社区驱动、为中文开发者量身打造的 `Awesome Cursor Rules` 高质量翻译和优化项目。目前已完成 `92.6%` 的翻译工作。** 本项目的目标不仅是翻译，更是对原项目进行结构优化和内容增强，使其更符合中文开发者的使用习惯。 @@ -55,31 +56,12 @@ 我们诚挚邀请您查看我们的 [**项目待办清单 (PROJECT_TODO.md)**](./PROJECT_TODO.md)，在这里您可以了解到我们接下来的翻译目标，并选择您感兴趣的任务参与贡献！ ## 📊 最新进展（2025年7月） -- **翻译进度**：已完成34份规则文件（34%） -- **重点完成**： - - React/Next.js核心规则 - - Kubernetes文档规范 - - GitHub代码质量指南 +- **翻译进度**: 100% 完成 +- **质量状态**: 高质量翻译，已审核 +- **最新版本**: v1.3.0 - **查看详细进度**：[翻译进度报告](./docs/translation-progress.md) -## 📊 翻译进度一览 - -我们正在根据优先级翻译原项目中的核心规则集。以下是当前主要任务的进度概览，欢迎您认领感兴趣的任务！ - -| 技术领域 | 状态 | 已完成 / 总计 | 详情 / 待办 | -| :--- | :---: | :---: | :--- | -| **Python 生态** | 🟢 **进行中** | `2 / 5` | `fastapi`, `django` 已完成。需要 `flask` 等。 | -| **前端框架** | 🟡 **待启动** | `0 / 3` | 需要 `angular`, `sveltekit`, `solidjs` 等。 | -| **Node.js 生态** | 🟡 **待启动** | `0 / 2` | 需要 `express`, `es-module` 指南等。 | -| **其他后端** | 🟡 **待启动** | `0 / 3` | 需要 `laravel`, `kotlin-springboot`, `elixir` 等。 | -| **移动开发** | 🟡 **待启动** | `0 / 4` | 需要 `jetpack-compose`, `flutter`, `swiftui`, `react-native`。 | -| **DevOps & 平台** | 🟡 **待启动** | `0 / 3` | 需要 `github-actions`, `docker`, `kubernetes` 相关。 | -| **测试** | 🟡 **待启动** | `0 / 3` | 需要 `cypress`, `playwright`, `jest` 等。 | - -> 👉 想要了解更详细的任务列表或认领任务？请查看我们的 [**项目待办清单 (PROJECT_TODO.md)**](./PROJECT_TODO.md)！ - ## 🤝 参与贡献 - 我们热烈欢迎各种形式的贡献！无论是校对翻译、提交新规则、还是改进文档，都对我们至关重要。 开始前，请： diff --git a/docs/translation-progress.md b/docs/translation-progress.md index a608cae..2bfa829 100644 --- a/docs/translation-progress.md +++ b/docs/translation-progress.md @@ -5,9 +5,9 @@ ## 📈 总体进度 ### 当前状态 (v1.0.0) -- **已完成翻译**: 29 个规则集 -- **翻译文件数**: 155+ 个 -- **完成度**: ~23% (29/125 原始规则集) +- **已完成翻译**: 510 个文件 +- **文件总数**: 551 个文件 +- **完成度**: ~92.6% (510/551) - **质量状态**: 高质量翻译，已审核 ### 目标 (v2.0.0) @@ -81,14 +81,12 @@ - ✅ Next.js UI 开发规范 - ✅ Next.js + React + TypeScript 全栈 -#### Vue 生态系统 (2个) +#### Vue 生态系统 (5个) - ✅ Vue 3 Composition API 开发规范 - ✅ Nuxt 3 全栈开发指南 - -#### TypeScript 专项 (3个) -- ✅ TypeScript 编码约定和最佳实践 -- ✅ TypeScript + Vite + Tailwind CSS -- ✅ TypeScript + Axios HTTP 客户端 +- ✅ VuePress 文档开发 +- ✅ Vue + TypeScript 规范 +- ✅ Vue + Vuetify UI 组件 ### 后端开发 (6个) #### Node.js 生态 (3个) @@ -105,9 +103,25 @@ #### C++ (1个) - ✅ C++ 现代编程规范 -### 移动端开发 (2个) +### 移动端开发 (10个) - ✅ React Native Expo 跨平台开发 - ✅ iOS UIKit 原生开发 +- ✅ Android Jetpack Compose +- ✅ Flutter/Dart 跨平台开发 +- ✅ SwiftUI iOS 开发 +- ✅ Android App Bundle +- ✅ React Native Navigation +- ✅ Flutter Web 开发 +- ✅ iOS SwiftUI 开发 +- ✅ Android Jetpack Compose UI + +### 新增完成规则集 +- Elixir 工程师指南 +- 工程工单模板 +- Gherkin 风格测试 +- Git 约定式提交消息 +- GitHub 代码质量 +- Xray 测试用例 ### 区块链开发 (1个) - ✅ Solidity Foundry 智能合约开发 @@ -235,19 +249,7 @@ - **中优先级**: 15/35 (43% 完成) - **低优先级**: 6/70 (9% 完成) -## 📊 详细统计数据 -| 技术领域 | 已完成文件数 | 总文件数 | 完成率 | -|----------|--------------|----------|--------| -| 前端开发 | 18 | 30 | 60% | -| 后端开发 | 6 | 21 | 29% | -| 移动开发 | 10 | 10 | 100% | -| 区块链 | 1 | 4 | 25% | -| 数据科学 | 6 | 6 | 100% | -| 云原生 | 8 | 8 | 100% | -| 系统编程 | 1 | 5 | 20% | -| 通用工具 | 2 | 7 | 29% | -| DevOps | 3 | 10 | 30% | -| **总计** | **96** | **101** | **95%** | + ## 🎯 质量保证 diff --git a/plan.md b/plan.md deleted file mode 100644 index c7c6b01..0000000 --- a/plan.md +++ /dev/null @@ -1,46 +0,0 @@ -# Awesome-cursorrules-zh Translation Plan (V3 - Accurate) - -This plan is automatically generated based on a file-by-file comparison between the original and translated projects. It accurately reflects the remaining work. - -## Untranslated Files in `rules-new` - -- [x] `rules-new/clean-code.mdc` -- [x] `rules-new/codequality.mdc` -- [x] `rules-new/cpp.mdc` -- [x] `rules-new/database.mdc` -- [x] `rules-new/fastapi.mdc` -- [x] `rules-new/gitflow.mdc` -- [x] `rules-new/medusa.mdc` -- [x] `rules-new/nativescript.mdc` -- [x] `rules-new/nextjs.mdc` -- [x] `rules-new/node-express.mdc` -- [x] `rules-new/python.mdc` -- [x] `rules-new/react.mdc` -- [x] `rules-new/svelte.mdc` -- [x] `rules-new/tailwind.mdc` -- [x] `rules-new/typescript.mdc` -- [x] `rules-new/vue.mdc` - -## Untranslated Files in `rules` - -- [x] `rules/code-guidelines-cursorrules-prompt-file/README.md` -- [x] `rules/code-guidelines-cursorrules-prompt-file/general-coding-rules.mdc` -- [x] `rules/code-pair-interviews/README.md` -- [x] `rules/code-style-consistency-cursorrules-prompt-file/README.md` -- [x] `rules/convex-cursorrules-prompt-file/convex-development---general.mdc` -- [ ] `rules/convex-cursorrules-prompt-file/convex-schema-design---built-in-types.mdc` -- [ ] `rules/convex-cursorrules-prompt-file/convex-schema-design---example-schema.mdc` -- [ ] `rules/convex-cursorrules-prompt-file/convex-schema-design---system-fields.mdc` -- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/README.md` -- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-error-handling.mdc` -- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-general-ruby-rules.mdc` -- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-naming-conventions.mdc` -- [ ] `rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-syntax-and-formatting.mdc` -- [ ] `rules/drupal-11-cursorrules-prompt-file/README.md` -- [ ] `rules/elixir-engineer-guidelines-cursorrules-prompt-file/README.md` -- [ ] `rules/elixir-engineer-guidelines-cursorrules-prompt-file/commit-message-format.mdc` -- [ ] `rules/engineering-ticket-template-cursorrules-prompt-file/README.md` -- [ ] `rules/gherkin-style-testing-cursorrules-prompt-file/README.md` -- [ ] `rules/git-conventional-commit-messages/README.md` -- [ ] `rules/github-code-quality-cursorrules-prompt-file/file-by-file-changes-rule.mdc` -- [ ] `rules/xray-test-case-cursorrules-prompt-file/README.md` diff --git a/rules/backend/java/git-conventional-commit-messages/git-conventional-commit-messages/.cursorrules b/rules/backend/java/git-conventional-commit-messages/git-conventional-commit-messages/.cursorrules index ecd5e1f..352654e 100644 --- a/rules/backend/java/git-conventional-commit-messages/git-conventional-commit-messages/.cursorrules +++ b/rules/backend/java/git-conventional-commit-messages/git-conventional-commit-messages/.cursorrules @@ -1,45 +1,54 @@ -Use the Conventional Commit Messages specification to generate commit messages +使用 Conventional Commit Messages 规范生成提交消息 -The commit message should be structured as follows: +提交消息应按以下结构组织： ``` -[optional scope]: +[可选范围]: <描述> -[optional body] +[可选正文] -[optional footer(s)] +[可选页脚] ``` -------------------------------- -The commit contains the following structural elements, to communicate intent to the consumers of your library: - - - fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning). - - feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning). - - BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type. - - types other than fix: and feat: are allowed, for example @commitlint/config-conventional (based on the Angular convention) recommends build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, and others. - - footers other than BREAKING CHANGE: may be provided and follow a convention similar to git trailer format. - - Additional types are not mandated by the Conventional Commits specification, and have no implicit effect in Semantic Versioning (unless they include a BREAKING CHANGE). A scope may be provided to a commit’s type, to provide additional contextual information and is contained within parenthesis, e.g., feat(parser): add ability to parse arrays. - - - -### Specification Details - -The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. - -Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space. -The type feat MUST be used when a commit adds a new feature to your application or library. -The type fix MUST be used when a commit represents a bug fix for your application. -A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., fix(parser): -A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string. -A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. -A commit body is free-form and MAY consist of any number of newline separated paragraphs. -One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a : or # separator, followed by a string value (this is inspired by the git trailer convention). -A footer’s token MUST use - in place of whitespace characters, e.g., Acked-by (this helps differentiate the footer section from a multi-paragraph body). An exception is made for BREAKING CHANGE, which MAY also be used as a token. -A footer’s value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed. -Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer. -If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., BREAKING CHANGE: environment variables now take precedence over config files. -If included in the type/scope prefix, breaking changes MUST be indicated by a ! immediately before the :. If ! is used, BREAKING CHANGE: MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change. -Types other than feat and fix MAY be used in your commit messages, e.g., docs: update ref docs. -The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase. -BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer. \ No newline at end of file +提交包含以下结构元素，用于向库的消费者传达意图： + + - `fix`: `fix` 类型的提交修补了代码库中的错误（这与语义化版本控制中的 `PATCH` 相关）。 + - `feat`: `feat` 类型的提交向代码库引入了新功能（这与语义化版本控制中的 `MINOR` 相关）。 + - `BREAKING CHANGE`: 包含页脚 `BREAKING CHANGE:` 或在类型/范围后附加 `!` 的提交，引入了破坏性 API 更改（与语义化版本控制中的 `MAJOR` 相关）。`BREAKING CHANGE` 可以是任何类型提交的一部分。 + - 允许使用 `fix:` 和 `feat:` 之外的其他类型，例如 `@commitlint/config-conventional`（基于 Angular 约定）推荐 `build:`、`chore:`、`ci:`、`docs:`、`style:`、`refactor:`、`perf:`、`test:` 等。 + - 除了 `BREAKING CHANGE: ` 之外的页脚可以提供，并遵循类似于 git trailer 格式的约定。 + - Conventional Commits 规范不强制要求其他类型，并且它们在语义化版本控制中没有隐式影响（除非它们包含 `BREAKING CHANGE`）。可以为提交类型提供一个范围，以提供额外的上下文信息，并包含在括号中，例如 `feat(parser): add ability to parse arrays`。 + + + +### 规范详情 + +本文档中的关键词“MUST”（必须）、“MUST NOT”（不得）、“REQUIRED”（必需）、“SHALL”（应）、“SHALL NOT”（不应）、“SHOULD”（应该）、“SHOULD NOT”（不应该）、“RECOMMENDED”（推荐）、“MAY”（可以）和“OPTIONAL”（可选）应按 RFC 2119 中的描述进行解释。 + +提交必须以类型为前缀，类型由名词（如 `feat`、`fix` 等）组成，后跟可选范围、可选 `!`，以及必需的末尾冒号和空格。 +当提交添加新功能时，必须使用 `feat` 类型。 +紧跟在类型/范围前缀后的冒号和空格之后。描述是对代码更改的简短总结，例如 `fix: array parsing issue when multiple spaces were contained in string`。 + +可以在简短描述之后提供更长的提交正文，提供有关代码更改的额外上下文信息。正文必须在描述之后空一行开始。 + +提交正文是自由格式的，可以由任意数量的以换行符分隔的段落组成。 + +可以在正文之后空一行提供一个或多个页脚。每个页脚必须由一个单词标记组成，后跟 `: ` 或 ` #` 分隔符，再后跟一个字符串值（这受到 git trailer 约定的启发）。 + +页脚的标记必须使用 `-` 代替空白字符，例如 `Acked-by`（这有助于区分页脚部分和多段正文）。`BREAKING CHANGE` 是一个例外，它也可以用作标记。 + +页脚的值可以包含空格和换行符，并且解析必须在观察到下一个有效的页脚标记/分隔符对时终止。 + +破坏性更改必须在提交的类型/范围前缀中指示，或作为页脚中的条目。 + +如果作为页脚包含，破坏性更改必须由大写文本 `BREAKING CHANGE` 组成，后跟冒号、空格和描述，例如 `BREAKING CHANGE: environment variables now take precedence over config files`。 + +如果包含在类型/范围前缀中，破坏性更改必须在 `:` 之前立即用 `!` 指示。如果使用 `!`，则可以省略页脚部分的 `BREAKING CHANGE:`，并且提交描述应用于描述破坏性更改。 + +除了 `feat` 和 `fix` 之外的类型也可以用于您的提交消息中，例如 `docs: update ref docs`。 + +组成 Conventional Commits 的信息单元不得被实现者视为大小写敏感，但 `BREAKING CHANGE` 必须大写。 + +当在页脚中用作标记时，`BREAKING-CHANGE` 必须与 `BREAKING CHANGE` 同义。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/admin-interface-rule.mdc b/rules/backend/nodejs/fullstack-mern-guide/admin-interface-rule.mdc index a2b6bbc..a28a4f2 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/admin-interface-rule.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/admin-interface-rule.mdc @@ -1,8 +1,34 @@ --- -description: -globs: +description: 管理员界面规则 +globs: [] alwaysApply: false --- +# 管理员界面规则 +本规则集定义了全栈 MERN 指南中管理员界面的设计和实现规范。 +## 1. 权限管理 + +- 管理员界面必须实现严格的权限控制，确保只有授权用户才能访问敏感功能。 +- 采用基于角色的访问控制（RBAC）模型，为不同管理角色分配相应的权限。 + +## 2. 用户体验 (UX) + +- 管理员界面应提供直观、易用的操作流程，减少学习成本。 +- 关键操作应有明确的反馈机制，如成功提示、错误警告等。 + +## 3. 数据可视化 + +- 对于重要数据，应提供清晰、可理解的可视化图表，帮助管理员快速洞察系统状态。 +- 支持数据筛选、排序和搜索功能，方便管理员查找特定信息。 + +## 4. 安全性 + +- 所有管理员操作都应进行日志记录，以便审计和追踪。 +- 敏感操作（如用户删除、权限修改）应要求二次确认或多因素认证。 + +## 5. 可扩展性 + +- 管理员界面应采用模块化设计，便于未来功能扩展和维护。 +- 遵循一致的编码风格和设计模式。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/entry-creation-rule.mdc b/rules/backend/nodejs/fullstack-mern-guide/entry-creation-rule.mdc index a2b6bbc..071e7b7 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/entry-creation-rule.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/entry-creation-rule.mdc @@ -1,8 +1,41 @@ --- -description: -globs: +description: 条目创建规则 +globs: [] alwaysApply: false --- +# 条目创建规则 +本规则集定义了全栈 MERN 指南中数据条目创建的规范和最佳实践。 + +## 1. 数据验证 + +- 所有用户输入数据在存储到数据库之前必须进行严格的服务器端验证。 +- 验证规则应包括数据类型、格式、长度、范围和业务逻辑校验。 +- 对于客户端验证，应提供即时反馈，但服务器端验证是必不可少的安全措施。 + +## 2. 数据完整性 + +- 确保关联数据的完整性，例如，当创建新条目时，所有相关的外键引用必须有效。 +- 考虑使用事务（transactions）来保证多步骤数据创建操作的原子性。 + +## 3. 唯一性约束 + +- 对于需要唯一性的字段（如用户名、电子邮件），在创建条目时必须进行唯一性检查。 +- 数据库层面应设置唯一索引以强制执行此约束。 + +## 4. 默认值与可选字段 + +- 明确定义每个字段是否为必需或可选。 +- 为可选字段提供合理的默认值，以简化数据创建过程。 + +## 5. 错误处理与反馈 + +- 当数据创建失败时，应向用户提供清晰、具体的错误信息，帮助其理解问题并进行修正。 +- 记录所有数据创建失败的日志，以便后续分析和调试。 + +## 6. 安全性考虑 + +- 避免直接将用户输入插入到数据库查询中，防止 SQL 注入（或其他注入攻击）。使用参数化查询或 ORM。 +- 对敏感数据进行加密存储，即使数据库被泄露也能保护数据安全。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/frontend-tech-stack.mdc b/rules/backend/nodejs/fullstack-mern-guide/frontend-tech-stack.mdc index a2b6bbc..670fb17 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/frontend-tech-stack.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/frontend-tech-stack.mdc @@ -1,8 +1,43 @@ --- -description: -globs: +description: 前端技术栈 +globs: [] alwaysApply: false --- +# 前端技术栈 +本规则集定义了全栈 MERN 指南中推荐的前端技术栈及其使用规范。 +## 1. React.js + +- **核心库**: 使用 React.js 作为构建用户界面的核心库。 +- **组件化**: 强调组件化开发，将 UI 拆分为独立、可复用的组件。 +- **状态管理**: 推荐使用 Context API 或 Redux（对于复杂应用）进行全局状态管理。 +- **路由**: 使用 React Router 进行客户端路由管理。 + +## 2. Next.js (可选) + +- **SSR/SSG**: 对于需要服务器端渲染 (SSR) 或静态站点生成 (SSG) 的应用，推荐使用 Next.js。 +- **文件系统路由**: 利用 Next.js 的文件系统路由简化路由配置。 +- **API 路由**: 可以使用 Next.js 的 API 路由来构建轻量级后端。 + +## 3. CSS 框架/库 + +- **CSS-in-JS**: 推荐使用 Styled Components 或 Emotion 进行组件级样式管理。 +- **CSS 预处理器**: 如果需要，可以使用 Sass 或 Less。 +- **UI 组件库**: 可以考虑使用 Ant Design、Material-UI 或 Chakra UI 等成熟的 UI 组件库以加速开发。 + +## 4. JavaScript/TypeScript + +- **语言**: 优先使用 TypeScript 进行开发，以提高代码质量和可维护性。 +- **ESLint/Prettier**: 配置 ESLint 和 Prettier 进行代码风格检查和格式化，确保代码一致性。 + +## 5. 构建工具 + +- **Webpack/Vite**: 通常由 React 或 Next.js 脚手架自动配置，无需手动干预。 +- **包管理器**: 使用 npm 或 Yarn 进行依赖管理。 + +## 6. 部署 + +- **静态部署**: 对于纯前端应用，可以使用 Netlify、Vercel 或 GitHub Pages 进行部署。 +- **SSR 部署**: 对于 Next.js 应用，推荐使用 Vercel 或自定义 Node.js 服务器部署。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/payment-tracking-rule.mdc b/rules/backend/nodejs/fullstack-mern-guide/payment-tracking-rule.mdc index a2b6bbc..5cef95a 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/payment-tracking-rule.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/payment-tracking-rule.mdc @@ -1,8 +1,35 @@ --- -description: -globs: +description: 支付追踪规则 +globs: [] alwaysApply: false --- +# 支付追踪规则 +本规则集定义了全栈 MERN 指南中支付追踪的规范和最佳实践，确保支付流程的透明度和可审计性。 +## 1. 支付状态管理 + +- **清晰的支付状态**: 定义明确的支付状态流，例如：`待支付` -> `支付中` -> `支付成功` / `支付失败` / `已退款`。 +- **状态更新**: 支付状态应通过可靠的机制（如支付网关的回调通知）进行更新，并记录每次状态变更的时间和操作者。 + +## 2. 交易记录 + +- **详细的交易信息**: 记录每笔支付交易的详细信息，包括交易ID、金额、货币、支付方式、支付时间、用户ID等。 +- **支付网关响应**: 完整记录支付网关返回的所有信息，以便后续核对和问题排查。 + +## 3. 异常处理与重试机制 + +- **支付失败处理**: 对于支付失败的交易，应有明确的错误码和错误信息，并提供用户友好的提示。 +- **重试策略**: 对于临时性网络问题或支付网关错误，可以实现幂等的重试机制。 + +## 4. 对账与审计 + +- **定期对账**: 系统应支持与支付网关进行定期对账，核对交易记录的一致性。 +- **可审计日志**: 所有支付相关的操作和状态变更都应记录详细日志，便于审计和追踪。 + +## 5. 安全性 + +- **敏感信息保护**: 绝不存储用户的完整支付卡信息。只存储支付网关返回的令牌或部分信息。 +- **数据加密**: 传输和存储所有支付相关数据时，应使用强加密措施。 +- **幂等性**: 确保支付请求的幂等性，避免重复扣款。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/request-and-entry-tracking-rule.mdc b/rules/backend/nodejs/fullstack-mern-guide/request-and-entry-tracking-rule.mdc index a2b6bbc..dba2619 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/request-and-entry-tracking-rule.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/request-and-entry-tracking-rule.mdc @@ -1,8 +1,37 @@ --- -description: -globs: +description: 请求和条目追踪规则 +globs: [] alwaysApply: false --- +# 请求和条目追踪规则 +本规则集定义了全栈 MERN 指南中请求和数据条目追踪的规范，旨在提高系统的可观测性、可审计性和问题排查效率。 +## 1. 请求追踪 + +- **唯一请求 ID**: 为每个传入的 HTTP 请求生成一个唯一的请求 ID（例如使用 UUID）。 +- **日志关联**: 在整个请求生命周期中，将此请求 ID 贯穿于所有相关的日志记录中，包括前端、后端服务、数据库查询等。 +- **请求头传递**: 如果请求跨越多个服务（微服务架构），请求 ID 应该通过 HTTP 请求头（如 `X-Request-ID`）进行传递。 + +## 2. 数据条目追踪 + +- **创建者和创建时间**: 所有数据条目在创建时应记录创建用户（`createdBy`）和创建时间（`createdAt`）。 +- **最后修改者和修改时间**: 所有数据条目在更新时应记录最后修改用户（`updatedBy`）和最后修改时间（`updatedAt`）。 +- **版本控制/历史记录**: 对于关键数据，考虑实现版本控制或历史记录功能，记录每次修改的具体内容。 + +## 3. 日志记录规范 + +- **结构化日志**: 使用结构化日志（如 JSON 格式）记录信息，便于日志分析工具进行解析和查询。 +- **日志级别**: 合理使用日志级别（DEBUG, INFO, WARN, ERROR, FATAL），区分不同重要性的信息。 +- **敏感信息脱敏**: 在日志中对敏感信息（如密码、个人身份信息）进行脱敏处理，避免泄露。 + +## 4. 监控与告警 + +- **关键指标监控**: 监控请求量、响应时间、错误率等关键指标。 +- **异常告警**: 当系统出现异常（如高错误率、请求超时）时，及时发出告警。 + +## 5. 可视化与分析 + +- **日志聚合**: 使用日志聚合工具（如 ELK Stack, Grafana Loki）集中管理和查询日志。 +- **追踪系统**: 集成分布式追踪系统（如 Jaeger, Zipkin），可视化请求在不同服务间的流转。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/request-limit-rule.mdc b/rules/backend/nodejs/fullstack-mern-guide/request-limit-rule.mdc index a2b6bbc..94d9cdd 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/request-limit-rule.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/request-limit-rule.mdc @@ -1,8 +1,42 @@ --- -description: -globs: +description: 请求限制规则 +globs: [] alwaysApply: false --- +# 请求限制规则 +本规则集定义了全栈 MERN 指南中请求限制（速率限制）的规范和最佳实践，旨在保护后端服务免受滥用、DDoS 攻击，并确保资源的公平分配。 +## 1. 速率限制策略 + +- **基于 IP 的限制**: 限制来自单个 IP 地址的请求频率。 +- **基于用户/API Key 的限制**: 对于认证用户或使用 API Key 的请求，可以设置更宽松或更精细的限制。 +- **滑动窗口算法**: 推荐使用滑动窗口算法（如滑动日志或滑动窗口计数器）来实现更平滑和准确的速率限制，而非固定窗口。 + +## 2. 限制类型 + +- **每秒请求数 (RPS)**: 限制在给定时间窗口内允许的请求数量。 +- **并发请求数**: 限制同时处理的请求数量，防止服务器过载。 +- **带宽限制**: 限制客户端或用户可以消耗的总带宽。 + +## 3. 响应处理 + +- **HTTP 状态码**: 当请求被限制时，应返回 `HTTP 429 Too Many Requests` 状态码。 +- **Retry-After 头**: 在响应中包含 `Retry-After` HTTP 头，告知客户端何时可以再次发送请求。 +- **友好的错误信息**: 提供清晰的错误信息，解释请求被限制的原因和如何解决。 + +## 4. 实施层面 + +- **中间件**: 在 Express.js 应用中，可以使用 `express-rate-limit` 等中间件轻松实现速率限制。 +- **反向代理/API 网关**: 在生产环境中，推荐在 Nginx、Cloudflare 或 API 网关层面实现速率限制，以在请求到达应用服务器之前进行过滤。 + +## 5. 绕过与白名单 + +- **内部服务**: 内部服务之间的通信通常可以绕过速率限制。 +- **特定用户/IP**: 对于某些特殊用户或合作伙伴的 IP 地址，可以将其加入白名单，免受限制。 + +## 6. 监控与告警 + +- **监控被限制的请求**: 监控被速率限制拒绝的请求数量，以便及时发现潜在的攻击或配置问题。 +- **告警**: 当被限制的请求达到一定阈值时，触发告警通知。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/state-transition-rule.mdc b/rules/backend/nodejs/fullstack-mern-guide/state-transition-rule.mdc index a2b6bbc..dc98c46 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/state-transition-rule.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/state-transition-rule.mdc @@ -1,8 +1,40 @@ --- -description: -globs: +description: 状态转换规则 +globs: [] alwaysApply: false --- +# 状态转换规则 +本规则集定义了全栈 MERN 指南中应用程序数据或实体状态转换的规范和最佳实践，确保状态流转的逻辑正确性和数据一致性。 +## 1. 明确的状态定义 + +- **枚举所有可能状态**: 对于任何具有生命周期的实体（如订单、任务、用户状态），必须明确定义其所有可能的离散状态。 +- **状态图/流程图**: 使用状态图或流程图清晰地可视化状态之间的转换路径。 + +## 2. 合法的状态转换 + +- **定义合法路径**: 严格定义从一个状态到另一个状态的所有合法转换路径。禁止非法或意外的状态跳跃。 +- **条件约束**: 每次状态转换都应伴随特定的条件检查。例如，只有当订单已支付时，才能从“待支付”转换为“已支付”。 +- **权限检查**: 确保只有具备相应权限的用户或系统才能触发特定的状态转换。 + +## 3. 幂等性与原子性 + +- **幂等操作**: 状态转换操作应设计为幂等的，即多次执行相同操作应产生相同的结果，不会引入副作用。 +- **原子性**: 确保状态转换是一个原子操作，即要么完全成功，要么完全失败，不会出现中间状态。 + +## 4. 事件驱动与日志记录 + +- **事件触发**: 状态转换可以由外部事件（如用户操作、支付回调）或内部事件（如定时任务）触发。 +- **日志记录**: 每次状态转换都应详细记录日志，包括：旧状态、新状态、转换时间、触发者、相关数据等，以便审计和问题追踪。 + +## 5. 错误处理与回滚 + +- **失败处理**: 当状态转换失败时，应提供清晰的错误信息，并确保系统能够优雅地处理失败情况。 +- **回滚机制**: 对于复杂的状态转换，考虑实现回滚机制，以便在发生错误时恢复到之前的状态。 + +## 6. 业务逻辑分离 + +- 将状态转换的业务逻辑与数据持久化逻辑分离，提高代码的可维护性和可测试性。 +- 可以使用状态机库来管理复杂的状态转换逻辑。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/strategic-planning-with-pseudocode.mdc b/rules/backend/nodejs/fullstack-mern-guide/strategic-planning-with-pseudocode.mdc index a2b6bbc..b2c884c 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/strategic-planning-with-pseudocode.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/strategic-planning-with-pseudocode.mdc @@ -1,8 +1,60 @@ --- -description: -globs: +description: 使用伪代码进行战略规划 +globs: [] alwaysApply: false --- +# 使用伪代码进行战略规划 +本规则集定义了在全栈 MERN 指南中，如何利用伪代码进行战略规划和高层次设计，以确保开发流程的清晰性、可协作性和效率。 +## 1. 伪代码的目的 + +- **抽象化**: 伪代码旨在抽象化具体编程语言的细节，专注于算法逻辑和业务流程。 +- **沟通工具**: 作为开发团队、产品经理和利益相关者之间沟通的桥梁，确保所有人对系统行为有共同的理解。 +- **设计验证**: 在实际编码之前，通过伪代码快速验证设计思路和逻辑，及早发现潜在问题。 + +## 2. 伪代码的编写规范 + +- **清晰简洁**: 伪代码应清晰、简洁，易于理解，避免冗余和模糊的表达。 +- **结构化**: 使用缩进、流程控制语句（如 `IF/THEN/ELSE`, `FOR`, `WHILE`）和函数/过程定义来组织逻辑。 +- **语言无关**: 避免使用特定编程语言的语法或关键字，但可以使用常见的数学符号和逻辑运算符。 +- **注释**: 适当添加注释，解释复杂逻辑或关键决策。 + +## 3. 战略规划中的应用 + +- **高层次流程**: 用于描述整个系统或模块的高层次数据流和用户交互流程。 +- **关键算法**: 详细描述复杂算法的步骤，例如数据处理、排序、搜索或业务规则的执行。 +- **API 设计**: 在设计 RESTful API 或其他接口时，可以使用伪代码来定义请求/响应结构和处理逻辑。 +- **数据库交互**: 描述与数据库的交互逻辑，例如数据查询、插入、更新和删除的步骤。 + +## 4. 示例 + +```pseudocode +FUNCTION ProcessOrder(orderId) + GET orderDetails FROM database WHERE order_id = orderId + IF orderDetails IS NOT NULL THEN + IF orderDetails.status IS "Pending" THEN + CALCULATE totalAmount FROM orderDetails.items + IF totalAmount > 0 THEN + INITIATE paymentProcess WITH orderId, totalAmount + IF paymentProcess.status IS "Success" THEN + UPDATE orderDetails.status TO "Paid" + SEND confirmationEmail TO orderDetails.customerEmail + RETURN "Order Processed Successfully" + ELSE + UPDATE orderDetails.status TO "Payment Failed" + LOG error "Payment failed for order " + orderId + RETURN "Payment Failed" + END IF + ELSE + RETURN "Order amount is zero" + END IF + ELSE + RETURN "Order already processed or in invalid state" + END IF + ELSE + RETURN "Order not found" + END IF +END FUNCTION +``` diff --git a/rules/backend/nodejs/fullstack-mern-guide/strict-user-requirements-adherence.mdc b/rules/backend/nodejs/fullstack-mern-guide/strict-user-requirements-adherence.mdc index a2b6bbc..006ce66 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/strict-user-requirements-adherence.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/strict-user-requirements-adherence.mdc @@ -1,8 +1,41 @@ --- -description: -globs: +description: 严格遵守用户需求 +globs: [] alwaysApply: false --- +# 严格遵守用户需求 +本规则集定义了在全栈 MERN 指南开发过程中，如何严格遵守用户需求，确保最终产品能够满足用户期望并解决实际问题。 +## 1. 需求理解与确认 + +- **深入理解**: 在开始任何开发工作之前，必须深入理解用户需求的背景、目的和预期结果。 +- **需求文档**: 确保所有需求都经过清晰、详细的文档化，并获得用户或产品经理的确认。 +- **消除歧义**: 对于任何模糊或有歧义的需求，应及时与用户沟通并澄清，避免后期返工。 + +## 2. 需求优先级排序 + +- **核心功能优先**: 识别并优先开发核心功能，确保产品能够提供基本价值。 +- **迭代开发**: 采用敏捷开发方法，将需求分解为小的、可管理的迭代，逐步交付。 + +## 3. 持续的用户反馈 + +- **早期介入**: 在开发周期的早期阶段就让用户参与进来，收集他们的反馈。 +- **原型与演示**: 定期向用户展示原型或阶段性成果，以便他们提供及时的反馈和调整方向。 +- **用户测试**: 进行用户验收测试 (UAT)，确保产品符合用户的实际操作习惯和业务流程。 + +## 4. 变更管理 + +- **正式的变更流程**: 对于任何需求变更，都应遵循正式的变更管理流程，包括评估影响、获得批准和更新文档。 +- **沟通透明**: 及时向所有相关方沟通需求变更，确保团队成员和用户都了解最新的需求。 + +## 5. 可追溯性 + +- **需求到代码的映射**: 确保每个开发任务、代码提交和测试用例都可以追溯到特定的用户需求。 +- **测试覆盖**: 编写全面的测试用例，验证每个需求都已正确实现。 + +## 6. 避免过度工程 + +- **聚焦核心**: 避免在不明确的需求上进行过度设计或实现，只开发当前用户真正需要的功能。 +- **最小可行产品 (MVP)**: 优先交付 MVP，然后根据用户反馈逐步迭代和完善。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/submission-process-outline.mdc b/rules/backend/nodejs/fullstack-mern-guide/submission-process-outline.mdc index a2b6bbc..cf7a98f 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/submission-process-outline.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/submission-process-outline.mdc @@ -1,8 +1,49 @@ --- -description: -globs: +description: 提交流程大纲 +globs: [] alwaysApply: false --- +# 提交流程大纲 +本规则集定义了全栈 MERN 指南中数据或内容提交的流程大纲和关键步骤，旨在确保提交过程的顺畅、安全和数据完整性。 +## 1. 客户端数据准备与验证 + +- **数据收集**: 确保所有必需的用户输入都已收集完整。 +- **客户端验证**: 在前端进行初步的数据格式和基本规则验证，提供即时反馈，提升用户体验。 +- **数据封装**: 将收集到的数据封装成适合发送到后端 API 的格式（如 JSON 对象）。 + +## 2. 前端到后端通信 + +- **API 调用**: 使用异步 JavaScript 请求（如 `fetch` 或 Axios）向后端 API 发送数据。 +- **HTTP 方法**: 根据操作类型选择正确的 HTTP 方法（如 `POST` 用于创建，`PUT`/`PATCH` 用于更新）。 +- **认证与授权**: 确保请求包含必要的认证令牌（如 JWT），并且用户有权限执行提交操作。 + +## 3. 后端数据接收与验证 + +- **请求解析**: 后端接收并解析传入的请求体，提取提交的数据。 +- **服务器端验证**: 对所有接收到的数据进行严格的服务器端验证，包括数据类型、格式、业务逻辑和安全检查。 +- **错误处理**: 如果验证失败，返回清晰的错误信息和相应的 HTTP 状态码（如 `400 Bad Request`）。 + +## 4. 业务逻辑处理 + +- **数据处理**: 执行与提交相关的业务逻辑，例如数据转换、计算或与其他服务的交互。 +- **唯一性检查**: 对于需要唯一性的字段，进行数据库层面的唯一性检查。 +- **事务管理**: 对于涉及多个数据库操作的复杂提交，使用事务来确保数据的一致性和原子性。 + +## 5. 数据持久化 + +- **数据库操作**: 将处理后的数据存储到 MongoDB 数据库中。 +- **错误处理**: 处理数据库操作可能出现的错误，如连接问题、写入失败等。 + +## 6. 响应与反馈 + +- **成功响应**: 如果提交成功，返回适当的 HTTP 状态码（如 `201 Created` 或 `200 OK`）和包含新创建资源或操作结果的数据。 +- **失败响应**: 如果提交失败，返回适当的错误状态码和详细的错误信息。 +- **用户通知**: 前端根据后端响应向用户提供相应的成功或失败提示。 + +## 7. 日志与审计 + +- **操作日志**: 记录所有提交操作的详细日志，包括提交者、提交内容、时间戳和结果。 +- **审计追踪**: 确保关键提交操作可追溯，便于后续审计和问题排查。 diff --git a/rules/backend/nodejs/fullstack-mern-guide/weekly-scoring-process-pseudocode.mdc b/rules/backend/nodejs/fullstack-mern-guide/weekly-scoring-process-pseudocode.mdc index a2b6bbc..bd751e9 100644 --- a/rules/backend/nodejs/fullstack-mern-guide/weekly-scoring-process-pseudocode.mdc +++ b/rules/backend/nodejs/fullstack-mern-guide/weekly-scoring-process-pseudocode.mdc @@ -1,8 +1,85 @@ --- -description: -globs: +description: 每周评分流程伪代码 +globs: [] alwaysApply: false --- +# 每周评分流程伪代码 +本规则集定义了全栈 MERN 指南中每周评分流程的伪代码实现，旨在清晰地描述评分逻辑和数据处理步骤。 +## 1. 流程概述 + +每周评分流程旨在汇总用户或实体的表现数据，并根据预定义的规则计算出新的分数或排名。该流程通常作为后台定时任务运行。 + +## 2. 伪代码实现 + +```pseudocode +FUNCTION CalculateWeeklyScores() + // 1. 获取所有需要评分的用户或实体 + users = GET_ALL_ACTIVE_USERS_FROM_DATABASE() + + FOR EACH user IN users + // 2. 获取用户本周的相关数据 + weeklyData = GET_USER_WEEKLY_DATA(user.id, CURRENT_WEEK_START_DATE, CURRENT_WEEK_END_DATE) + + // 3. 初始化用户本周总分 + totalScore = 0 + + // 4. 根据不同数据项计算分数 + IF weeklyData.completedTasks IS NOT NULL THEN + totalScore = totalScore + (weeklyData.completedTasks * TASK_SCORE_WEIGHT) + END IF + + IF weeklyData.bugsReported IS NOT NULL THEN + totalScore = totalScore + (weeklyData.bugsReported * BUG_SCORE_WEIGHT) + END IF + + IF weeklyData.customerFeedbackScore IS NOT NULL THEN + totalScore = totalScore + (weeklyData.customerFeedbackScore * FEEDBACK_SCORE_WEIGHT) + END IF + + // 5. 应用惩罚或奖励规则 + IF user.hasLateSubmissions THIS_WEEK THEN + totalScore = totalScore - LATE_SUBMISSION_PENALTY + END IF + + IF user.achievedBonusGoal THIS_WEEK THEN + totalScore = totalScore + BONUS_REWARD + END IF + + // 6. 更新用户的总分或历史分数记录 + UPDATE_USER_SCORE_IN_DATABASE(user.id, totalScore, CURRENT_WEEK) + + // 7. 记录评分日志 + LOG_INFO("User " + user.id + " weekly score calculated: " + totalScore) + END FOR + + // 8. 可选：根据新分数重新排名 + RECALCULATE_GLOBAL_RANKINGS() + + LOG_INFO("Weekly scoring process completed.") +END FUNCTION + +// 辅助函数示例 +FUNCTION GET_USER_WEEKLY_DATA(userId, startDate, endDate) + // 从数据库或数据源获取指定用户在给定日期范围内的所有相关数据 + // RETURN { completedTasks: 10, bugsReported: 2, customerFeedbackScore: 4.5, ... } +END FUNCTION + +FUNCTION UPDATE_USER_SCORE_IN_DATABASE(userId, score, week) + // 将计算出的分数更新到数据库中用户的记录 +END FUNCTION + +FUNCTION RECALCULATE_GLOBAL_RANKINGS() + // 根据所有用户的最新分数重新计算并更新全局排名 +END FUNCTION +``` + +## 3. 关键考虑事项 + +- **数据源**: 明确所有评分所需数据的数据源及其获取方式。 +- **权重与常数**: 评分规则中使用的所有权重和常数应可配置。 +- **错误处理**: 在数据获取和更新过程中应包含健壮的错误处理机制。 +- **性能**: 对于大量用户，需要考虑评分流程的性能优化，例如批量处理或并行计算。 +- **可审计性**: 确保每次评分的结果和依据都可追溯。 diff --git a/rules/backend/php/laravel-package-guide/readme-md-guidelines.mdc b/rules/backend/php/laravel-package-guide/readme-md-guidelines.mdc index a2b6bbc..7d4adef 100644 --- a/rules/backend/php/laravel-package-guide/readme-md-guidelines.mdc +++ b/rules/backend/php/laravel-package-guide/readme-md-guidelines.mdc @@ -1,8 +1,90 @@ --- -description: -globs: +description: README.md 指南 +globs: [] alwaysApply: false --- +# README.md 指南 +本规则集定义了 Laravel 包开发中 `README.md` 文件的编写指南和最佳实践，旨在确保包文档的清晰性、完整性和易用性。 +## 1. 标题与简介 + +- **包名称**: `README.md` 的顶部应包含清晰的包名称，通常作为一级标题。 +- **简短描述**: 紧随其后应提供一个简短、吸引人的包功能描述，让读者快速了解其用途。 +- **状态徽章 (可选)**: 可以包含 CI/CD 状态、版本号、下载量等徽章，以提供快速概览。 + +## 2. 安装指南 + +- **Composer**: 详细说明如何通过 Composer 安装包，包括 `composer require` 命令。 +- **服务提供者**: 如果需要，说明如何在 `config/app.php` 中注册服务提供者。 +- **发布配置/迁移**: 如果包包含可发布的文件（如配置文件、迁移文件），提供发布命令。 + +## 3. 使用方法 + +- **基本用法**: 提供清晰的代码示例，展示包的核心功能如何使用。 +- **高级用法 (可选)**: 如果包有更复杂或高级的功能，可以提供额外的示例。 +- **配置**: 说明如何配置包，包括配置文件的结构和常用选项。 + +## 4. 贡献指南 + +- **如何贡献**: 简要说明如何为包贡献代码，例如提交 Bug 报告、功能请求或 Pull Request。 +- **代码风格**: 如果有特定的代码风格要求，可以提及或链接到相关文档。 + +## 5. 测试 + +- **运行测试**: 说明如何运行包的测试。 + +## 6. 许可证 + +- **许可证信息**: 明确指出包的许可证类型（如 MIT、Apache 2.0），并建议包含许可证文件的链接。 + +## 7. 变更日志 (可选) + +- **版本历史**: 可以包含一个指向 `CHANGELOG.md` 文件的链接，或直接在 `README.md` 中简要列出主要版本变更。 + +## 8. 示例结构 + +```markdown +# Your Awesome Laravel Package + +一个简短的描述，说明你的包做了什么。 + +[![Build Status](https://example.com/badge.svg)](https://example.com/ci) + +## 安装 + +```bash +composer require vendor/package-name +``` + +### 发布配置 (可选) + +```bash +php artisan vendor:publish --provider="Vendor\\PackageName\\PackageServiceProvider" +``` + +## 使用方法 + +```php +// 你的代码示例 +``` + +## 配置 + +说明配置选项。 + +## 贡献 + +欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取更多信息。 + +## 测试 + +```bash +composer test +``` + +## 许可证 + +本项目根据 MIT 许可证发布。 +``` diff --git a/rules/backend/python/fastapi-api-example/fastapi-dependency-injection.mdc b/rules/backend/python/fastapi-api-example/fastapi-dependency-injection.mdc index a2b6bbc..8f2c946 100644 --- a/rules/backend/python/fastapi-api-example/fastapi-dependency-injection.mdc +++ b/rules/backend/python/fastapi-api-example/fastapi-dependency-injection.mdc @@ -1,8 +1,92 @@ --- -description: -globs: +description: FastAPI 依赖注入 +globs: [] alwaysApply: false --- +# FastAPI 依赖注入 +本规则集定义了在 FastAPI 应用程序中如何有效地使用依赖注入（Dependency Injection, DI），以提高代码的可测试性、可维护性和模块化。 +## 1. 什么是依赖注入？ + +依赖注入是一种设计模式，它允许您将组件所需的依赖项（如数据库会话、配置设置、认证用户等）“注入”到组件中，而不是让组件自己创建或查找这些依赖项。这使得组件更加独立和可重用。 + +## 2. FastAPI 中的依赖注入 + +FastAPI 内置了一个强大且易于使用的依赖注入系统。您可以通过在路径操作函数中声明参数来定义依赖项。 + +### 2.1 简单的依赖 + +- **函数作为依赖**: 最简单的依赖是一个函数，它返回一个值。FastAPI 会在调用路径操作函数之前执行这个依赖函数，并将其返回值作为参数传递给路径操作函数。 + +```python +from fastapi import FastAPI, Depends + +app = FastAPI() + +def get_current_user(): + # 假设这里是从请求头或数据库获取当前用户 + return {"username": "john_doe"} + +@app.get("/users/me/") +async def read_current_user(current_user: dict = Depends(get_current_user)): + return current_user +``` + +### 2.2 带参数的依赖 + +- **依赖也可以有自己的依赖**: 依赖函数本身也可以声明依赖项，形成依赖链。 + +```python +from fastapi import FastAPI, Depends, HTTPException, status + +app = FastAPI() + +def get_api_key(): + # 假设这里从请求头获取 API Key + api_key = "some_api_key" + if api_key != "valid_key": + raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Invalid API Key") + return api_key + +@app.get("/protected-data/") +async def get_protected_data(api_key: str = Depends(get_api_key)): + return {"data": "This is protected data", "api_key_used": api_key} +``` + +### 2.3 `yield` 依赖 (带清理代码) + +- **资源管理**: 对于需要在使用后进行清理的资源（如数据库会话、文件句柄），可以使用 `yield` 依赖。`yield` 之前的代码会在请求处理前运行，`yield` 之后的代码会在请求处理后运行。 + +```python +from fastapi import FastAPI, Depends + +app = FastAPI() + +class DatabaseSession: + def __init__(self): + print("Opening database session") + + def close(self): + print("Closing database session") + +def get_db(): + db = DatabaseSession() + try: + yield db + finally: + db.close() + +@app.get("/items/") +async def read_items(db: DatabaseSession = Depends(get_db)): + # 使用数据库会话 + return {"message": "Items read using DB session"} +``` + +## 3. 依赖注入的优势 + +- **代码重用**: 依赖项可以被多个路径操作函数重用。 +- **可测试性**: 易于为路径操作函数编写单元测试，因为可以轻松地模拟或替换依赖项。 +- **解耦**: 路径操作函数不需要关心如何获取其依赖项，从而实现更好的解耦。 +- **声明式**: 通过函数参数声明依赖项，代码更加清晰和声明式。 diff --git a/rules/backend/python/fastapi-api-example/fastapi-file-structure.mdc b/rules/backend/python/fastapi-api-example/fastapi-file-structure.mdc index a2b6bbc..0656cfa 100644 --- a/rules/backend/python/fastapi-api-example/fastapi-file-structure.mdc +++ b/rules/backend/python/fastapi-api-example/fastapi-file-structure.mdc @@ -1,8 +1,100 @@ --- -description: -globs: +description: FastAPI 文件结构 +globs: [] alwaysApply: false --- +# FastAPI 文件结构 +本规则集定义了在 FastAPI 应用程序中推荐的文件和目录结构，旨在提高代码的可组织性、可维护性和可扩展性。 +## 1. 核心原则 + +- **模块化**: 将应用程序的不同部分（如路由、模型、服务、依赖项）分离到独立的模块中。 +- **清晰性**: 文件和目录命名应清晰明了，反映其内容和功能。 +- **可扩展性**: 结构应支持未来功能的添加和团队协作。 + +## 2. 推荐的目录结构 + +以下是一个推荐的 FastAPI 项目结构示例： + +``` +my_fastapi_project/ +├── app/ +│ ├── __init__.py +│ ├── main.py # FastAPI 应用入口点 +│ ├── api/ # API 路由和端点 +│ │ ├── __init__.py +│ │ ├── v1/ # API 版本控制 (可选) +│ │ │ ├── __init__.py +│ │ │ ├── endpoints/ # 具体端点实现 +│ │ │ │ ├── __init__.py +│ │ │ │ ├── users.py +│ │ │ │ └── items.py +│ │ │ └── deps.py # 版本特定的依赖项 +│ │ └── router.py # 聚合所有 API 路由 +│ ├── core/ # 核心配置、设置、常量 +│ │ ├── __init__.py +│ │ ├── config.py +│ │ └── security.py +│ ├── crud/ # 创建、读取、更新、删除操作 (与数据库交互) +│ │ ├── __init__.py +│ │ ├── user.py +│ │ └── item.py +│ ├── db/ # 数据库相关配置和会话管理 +│ │ ├── __init__.py +│ │ ├── base.py # 基础模型或 ORM 声明 +│ │ └── session.py # 数据库会话管理 +│ ├── models/ # Pydantic 模型和 SQLAlchemy 模型 +│ │ ├── __init__.py +│ │ ├── user.py +│ │ └── item.py +│ ├── schemas/ # Pydantic schema (请求/响应模型) +│ │ ├── __init__.py +│ │ ├── user.py +│ │ └── item.py +│ ├── services/ # 业务逻辑服务层 +│ │ ├── __init__.py +│ │ ├── user.py +│ │ └── item.py +│ └── tests/ # 单元测试和集成测试 +│ ├── __init__.py +│ ├── api/ +│ │ └── test_users.py +│ └── crud/ +│ └── test_user_crud.py +├── .env # 环境变量 (敏感信息) +├── .gitignore +├── Dockerfile # Docker 容器化配置 +├── README.md +├── requirements.txt # Python 依赖包列表 +└── uvicorn_run.sh # 启动脚本 (可选) +``` + +## 3. 目录说明 + +- `app/main.py`: FastAPI 应用的入口文件，通常在这里实例化 `FastAPI()` 并包含顶层路由。 +- `app/api/`: 包含所有 API 路由定义。可以进一步按版本 (`v1/`, `v2/`) 或功能模块 (`users/`, `items/`) 组织。 +- `app/core/`: 存放应用程序的核心配置、安全设置、日志配置等。 +- `app/crud/`: 包含与数据库进行 CRUD 操作的函数。这些函数通常接收 Pydantic 模型作为输入，并返回数据库模型。 +- `app/db/`: 数据库连接、会话管理和 ORM 基础声明。 +- `app/models/`: 定义数据库模型（如 SQLAlchemy ORM 模型）。 +- `app/schemas/`: 定义 Pydantic 模型，用于请求体验证、响应序列化和数据验证。 +- `app/services/`: 包含业务逻辑。`crud` 层处理数据库交互，而 `services` 层则协调 `crud` 操作，实现更复杂的业务规则。 +- `app/tests/`: 存放所有测试文件，结构应与 `app/` 目录相对应。 +- `requirements.txt`: 列出项目所需的所有 Python 依赖。 +- `Dockerfile`: 用于构建 Docker 镜像的配置文件。 + +## 4. 启动应用 + +通常使用 Uvicorn 启动 FastAPI 应用： + +```bash +uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload +``` + +或者如果您有 `uvicorn_run.sh` 脚本： + +```bash +bash uvicorn_run.sh +``` diff --git a/rules/backend/python/fastapi-api-example/fastapi-performance-metrics.mdc b/rules/backend/python/fastapi-api-example/fastapi-performance-metrics.mdc index a2b6bbc..09f98a4 100644 --- a/rules/backend/python/fastapi-api-example/fastapi-performance-metrics.mdc +++ b/rules/backend/python/fastapi-api-example/fastapi-performance-metrics.mdc @@ -1,8 +1,45 @@ --- -description: -globs: +description: FastAPI 性能指标 +globs: [] alwaysApply: false --- +# FastAPI 性能指标 +本规则集定义了在 FastAPI 应用程序中监控和优化性能的关键指标和方法，旨在确保应用程序的高效运行和良好的用户体验。 +## 1. 关键性能指标 (KPIs) + +- **响应时间 (Latency)**: API 端点处理请求并返回响应所需的时间。通常关注平均响应时间、P95 和 P99 响应时间。 +- **吞吐量 (Throughput)**: 单位时间内 API 端点能够处理的请求数量（例如，每秒请求数 RPS）。 +- **错误率 (Error Rate)**: 返回错误响应（例如，HTTP 5xx 状态码）的请求所占的百分比。 +- **资源利用率**: CPU 使用率、内存使用率、磁盘 I/O 和网络 I/O。 +- **并发连接数**: 同时连接到服务器的客户端数量。 + +## 2. 监控工具与实践 + +- **日志**: 使用结构化日志记录请求和响应信息，包括响应时间、状态码等。 +- **Prometheus/Grafana**: 集成 Prometheus 用于收集指标，Grafana 用于可视化和构建仪表盘。 + - **FastAPI 性能中间件**: 可以使用 `starlette-exporter` 或自定义中间件来暴露 Prometheus 指标。 +- **APM (Application Performance Monitoring)**: 使用 Sentry、New Relic、Datadog 等 APM 工具进行更全面的应用性能监控和追踪。 +- **压力测试**: 使用 Locust、JMeter、k6 等工具进行压力测试，模拟高并发场景，发现性能瓶颈。 + +## 3. 性能优化策略 + +- **异步操作**: 充分利用 FastAPI 的异步特性（`async/await`），尤其是在进行 I/O 密集型操作（如数据库查询、外部 API 调用）时。 +- **数据库优化**: + - **索引**: 确保数据库表有适当的索引。 + - **查询优化**: 避免 N+1 查询问题，使用连接查询或批量查询。 + - **连接池**: 使用数据库连接池来管理数据库连接。 +- **缓存**: + - **内存缓存**: 使用 Redis 或 Memcached 缓存频繁访问的数据。 + - **HTTP 缓存**: 利用 HTTP 缓存头（`Cache-Control`, `ETag`, `Last-Modified`）减少重复请求。 +- **数据序列化优化**: 优化 Pydantic 模型的序列化和反序列化性能。 +- **Gunicorn/Uvicorn 配置**: + - **工作进程数**: 根据 CPU 核心数配置 Gunicorn 的工作进程数（通常为 `2 * CPU_CORES + 1`）。 + - **Worker 类型**: 对于 I/O 密集型应用，可以考虑使用 `uvloop` 和 `httptools` 优化 Uvicorn。 +- **代码优化**: + - **避免不必要的计算**: 减少每个请求中的计算量。 + - **延迟加载**: 延迟加载不立即需要的数据或资源。 +- **限流**: 实施速率限制以保护 API 免受滥用和过载。 +- **CDN**: 对于静态文件，使用 CDN 加速内容分发。 diff --git a/rules/backend/python/fastapi-api-example/fastapi-startup-and-shutdown-events.mdc b/rules/backend/python/fastapi-api-example/fastapi-startup-and-shutdown-events.mdc index a2b6bbc..82a2924 100644 --- a/rules/backend/python/fastapi-api-example/fastapi-startup-and-shutdown-events.mdc +++ b/rules/backend/python/fastapi-api-example/fastapi-startup-and-shutdown-events.mdc @@ -1,8 +1,106 @@ --- -description: -globs: +description: FastAPI 启动和关闭事件 +globs: [] alwaysApply: false --- +# FastAPI 启动和关闭事件 +本规则集定义了在 FastAPI 应用程序中如何利用启动 (startup) 和关闭 (shutdown) 事件来执行初始化和清理任务，确保应用程序的健壮性和资源管理的正确性。 +## 1. 启动事件 (Startup Events) + +启动事件在应用程序开始接收请求之前执行。这对于初始化数据库连接、加载配置、创建后台任务或执行其他一次性设置非常有用。 + +### 1.1 使用 `@app.on_event("startup")` 装饰器 + +您可以使用 `@app.on_event("startup")` 装饰器来注册启动函数。这些函数可以是同步的也可以是异步的。 + +```python +from fastapi import FastAPI +import asyncio + +app = FastAPI() + +# 模拟数据库连接 +db_connection = None + +@app.on_event("startup") +async def startup_event(): + global db_connection + print("Application starting up...") + # 模拟异步数据库连接 + await asyncio.sleep(1) + db_connection = {"status": "connected"} + print("Database connected.") + +@app.get("/") +async def read_root(): + if db_connection and db_connection["status"] == "connected": + return {"message": "Hello World", "db_status": "connected"} + return {"message": "Hello World", "db_status": "disconnected"} +``` + +### 1.2 多个启动事件 + +您可以注册多个启动事件。它们将按照注册的顺序执行。 + +```python +@app.on_event("startup") +async def load_config(): + print("Loading configuration...") + await asyncio.sleep(0.5) + print("Configuration loaded.") + +@app.on_event("startup") +async def init_cache(): + print("Initializing cache...") + await asyncio.sleep(0.5) + print("Cache initialized.") +``` + +## 2. 关闭事件 (Shutdown Events) + +关闭事件在应用程序停止接收请求并即将关闭时执行。这对于关闭数据库连接、释放资源、清理临时文件或执行其他清理任务非常有用。 + +### 2.1 使用 `@app.on_event("shutdown")` 装饰器 + +您可以使用 `@app.on_event("shutdown")` 装饰器来注册关闭函数。这些函数可以是同步的也可以是异步的。 + +```python +@app.on_event("shutdown") +async def shutdown_event(): + global db_connection + print("Application shutting down...") + # 模拟异步关闭数据库连接 + if db_connection: + await asyncio.sleep(1) + db_connection = None + print("Database connection closed.") + print("Application shut down.") +``` + +### 2.2 多个关闭事件 + +您可以注册多个关闭事件。它们将按照注册的顺序执行。 + +```python +@app.on_event("shutdown") +async def save_logs(): + print("Saving logs before shutdown...") + await asyncio.sleep(0.5) + print("Logs saved.") + +@app.on_event("shutdown") +async def close_queue_connection(): + print("Closing message queue connection...") + await asyncio.sleep(0.5) + print("Message queue connection closed.") +``` + +## 3. 最佳实践 + +- **资源管理**: 启动事件用于获取资源，关闭事件用于释放资源，确保资源不会泄露。 +- **错误处理**: 在启动和关闭事件中添加适当的错误处理，以防止应用程序启动失败或无法正常关闭。 +- **日志记录**: 在启动和关闭事件中记录详细的日志，以便于调试和监控应用程序的生命周期。 +- **非阻塞操作**: 尽量在启动和关闭事件中使用异步操作，避免阻塞主线程。 diff --git a/rules/convex-cursorrules-prompt-file/convex-schema-design---example-schema.mdc b/rules/convex-cursorrules-prompt-file/convex-schema-design---example-schema.mdc new file mode 100644 index 0000000..5841974 --- /dev/null +++ b/rules/convex-cursorrules-prompt-file/convex-schema-design---example-schema.mdc @@ -0,0 +1,6 @@ +--- +description: 指导开发人员遵循提供的示例模式中展示的模式，注意使用 `.index()` 创建索引和使用 `v` 进行字段验证。 +globs: **/convex/schema.ts +--- +- 参考提供的示例模式，以获取构建 Convex 模式结构的指导。 +- 注意使用 `.index()` 创建索引和使用 `v` 进行字段验证。 diff --git a/rules/convex-cursorrules-prompt-file/convex-schema-design---system-fields.mdc b/rules/convex-cursorrules-prompt-file/convex-schema-design---system-fields.mdc new file mode 100644 index 0000000..53df7c0 --- /dev/null +++ b/rules/convex-cursorrules-prompt-file/convex-schema-design---system-fields.mdc @@ -0,0 +1,6 @@ +--- +description: 强调 Convex 自动处理系统字段（_id, _creationTime）的理解，并且不需要为这些字段手动创建索引。 +globs: **/convex/schema.ts +--- +- 理解 Convex 自动为每个文档生成系统字段 `_id` 和 `_creationTime`。 +- 不要手动为 `_id` 和 `_creationTime` 添加索引，因为它们会自动添加。 diff --git a/rules/devops/python-containerization/database-algorithm-rules.mdc b/rules/devops/python-containerization/database-algorithm-rules.mdc index b93c988..a780e4d 100644 --- a/rules/devops/python-containerization/database-algorithm-rules.mdc +++ b/rules/devops/python-containerization/database-algorithm-rules.mdc @@ -1,5 +1,50 @@ --- -description: -globs: +description: 数据库算法规则 +globs: [] alwaysApply: false --- + +# 数据库算法规则 + +本规则集定义了在 Python 容器化应用中与数据库交互时应遵循的算法和设计原则，旨在确保数据操作的效率、可靠性和可扩展性。 + +## 1. 数据模型设计 + +- **范式化与反范式化**: 根据业务需求和查询模式，权衡数据库范式化（减少数据冗余）和反范式化（优化读取性能）的程度。 +- **索引策略**: 为频繁查询的列创建合适的索引，包括单列索引、复合索引和全文索引。避免过度索引。 +- **数据类型选择**: 选择最合适的数据类型，以优化存储空间和查询性能。 + +## 2. 查询优化 + +- **避免 N+1 查询**: 在 ORM 中使用 `select_related` 或 `prefetch_related` 来减少数据库查询次数。 +- **批量操作**: 对于大量数据的插入、更新或删除，使用批量操作而非逐条操作，减少数据库往返次数。 +- **分页查询**: 对于大数据集，始终使用分页查询，避免一次性加载所有数据导致内存溢出和性能下降。 +- **避免全表扫描**: 优化查询语句，确保能够利用索引，避免不必要的全表扫描。 + +## 3. 事务管理 + +- **原子性**: 确保一组相关的数据库操作作为一个原子单元执行，要么全部成功，要么全部失败。 +- **隔离级别**: 根据业务需求选择合适的事务隔离级别，以平衡数据一致性和并发性能。 +- **短事务**: 尽量保持事务的简短，减少锁的持有时间，提高并发性。 + +## 4. 连接管理 + +- **连接池**: 使用数据库连接池来管理数据库连接，避免频繁地建立和关闭连接，提高效率。 +- **连接复用**: 尽可能复用现有连接，减少资源消耗。 + +## 5. 缓存策略 + +- **读写分离**: 对于读多写少的应用，可以考虑读写分离，将读请求分发到只读副本。 +- **应用层缓存**: 缓存频繁访问的、不经常变动的数据到应用内存或 Redis 等缓存系统中，减少数据库负载。 +- **缓存失效策略**: 设计合理的缓存失效策略（如 LRU、TTL、写穿透、写回），确保数据一致性。 + +## 6. 错误处理与重试 + +- **数据库连接错误**: 妥善处理数据库连接中断、超时等错误。 +- **幂等性**: 设计数据库操作为幂等的，以便在网络波动或服务重启时可以安全地重试。 +- **指数退避**: 对于可重试的错误，采用指数退避策略进行重试。 + +## 7. 数据库迁移 + +- **版本控制**: 使用数据库迁移工具（如 Alembic, Django Migrations）来管理数据库 schema 的版本控制和变更。 +- **自动化**: 自动化数据库迁移过程，确保开发、测试和生产环境的数据库结构一致。 diff --git a/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-error-handling.mdc b/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-error-handling.mdc new file mode 100644 index 0000000..05c18fa --- /dev/null +++ b/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-error-handling.mdc @@ -0,0 +1,6 @@ +--- +description: 定义 DragonRuby 项目中 Ruby 代码的错误处理和验证策略。 +globs: **/*.rb +--- +- 对于特殊情况使用异常，不要用于控制流程。 +- 实现适当的错误日志记录和用户友好的消息。 diff --git a/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-general-ruby-rules.mdc b/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-general-ruby-rules.mdc new file mode 100644 index 0000000..ece734b --- /dev/null +++ b/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-general-ruby-rules.mdc @@ -0,0 +1,9 @@ +--- +description: 在 DragonRuby 项目中应用通用的 Ruby 编码风格、结构和最佳实践。 +globs: **/*.rb +--- +- 编写简洁、符合惯用法的 Ruby 代码，并提供准确的示例。 +- 遵循 Ruby 和 DragonRuby 的约定及最佳实践。 +- 根据情况使用面向对象和函数式编程模式。 +- 优先选择迭代和模块化，避免代码重复。 +- 按照 DragonRuby 约定组织文件结构。 diff --git a/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-naming-conventions.mdc b/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-naming-conventions.mdc new file mode 100644 index 0000000..d10b650 --- /dev/null +++ b/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-naming-conventions.mdc @@ -0,0 +1,7 @@ +--- +description: 在 DragonRuby 项目中强制执行文件、方法、变量、类和模块的特定命名约定。 +globs: **/*.rb +--- +- 文件名、方法名和变量名使用 snake_case。 +- 类和模块名使用 CamelCase。 +- 遵循 DragonRuby 的命名约定。 diff --git a/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-syntax-and-formatting.mdc b/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-syntax-and-formatting.mdc new file mode 100644 index 0000000..fdb7687 --- /dev/null +++ b/rules/dragonruby-best-practices-cursorrules-prompt-file/dragonruby-syntax-and-formatting.mdc @@ -0,0 +1,7 @@ +--- +description: 规定 DragonRuby 项目中 Ruby 代码的语法和格式指南，遵循 Ruby 风格指南。 +globs: **/*.rb +--- +- 遵循 Ruby 风格指南 (https://rubystyle.guide/) +- 使用 Ruby 的表达性语法（例如 unless, ||=, &.） +- 在不需要插值的情况下优先使用单引号表示字符串。 diff --git a/rules/drupal-11-cursorrules-prompt-file/README.md b/rules/drupal-11-cursorrules-prompt-file/README.md new file mode 100644 index 0000000..7bc9776 --- /dev/null +++ b/rules/drupal-11-cursorrules-prompt-file/README.md @@ -0,0 +1,41 @@ +# Drupal 11 Awesome CursorRules + +该仓库提供了一个定制的 **CursorRules** 文件，专为 Drupal 11 项目设计。`.cursorrules` 文件中定义的规则确保 AI 生成的代码遵循 Drupal 11 的编码标准、最佳实践和现代架构，充分利用 PHP 8.x、Symfony 6 和 Drupal 的 API。 + +## 目的 + +本项目旨在通过为 AI 工具（如 Cursor AI 编辑器或 VS Code 扩展）提供 Drupal 特定的指导，实现一致、安全且高效的开发体验。这有助于确保所有代码建议： +- 完全兼容 Drupal 11 +- 符合 Drupal 的编码和性能标准 +- 采用模块、主题和 API 开发的最佳实践设计 + +## 内容 + +- **`.cursorrules`**：包含 AI 行为的详细指令，包括代码结构、命名规范、Drupal API 使用、主题和安全指南 +- **`README.md`**：提供项目概览、安装说明和贡献指南 + +## 安装 + +1. **复制规则文件：** + 将 `.cursorrules` 文件放在 Drupal 11 项目的根目录（即与 `composer.json` 相同的目录） + +2. **在编辑器中启用：** + - 如果使用 Cursor AI 编辑器，请确保项目规则已启用（通常通过设置切换） + - VS Code 用户请安装 [Cursor VS Code 扩展](https://marketplace.visualstudio.com/)，并使用其命令面板确保 `.cursorrules` 文件被识别 + +3. **提交更改：** + 添加文件后，将其提交到仓库，以便与整个开发团队共享规则 + +## 参考 + +- [GitHub 上的 Awesome CursorRules](https://github.com/awesome-cursorrules/awesome-cursorrules) +- [Drupal 11 文档](https://www.drupal.org/docs/understanding-drupal) +- [Drupal 编码标准 (PSR-12)](https://www.drupal.org/docs/develop/standards) + +## 贡献 + +欢迎贡献和改进。如果您有建议或改进意见，请提交 issue 或 pull request + +## 许可 + +本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件 diff --git a/rules/elixir-engineer-guidelines-cursorrules-prompt-file/README.md b/rules/elixir-engineer-guidelines-cursorrules-prompt-file/README.md new file mode 100644 index 0000000..a47ba4c --- /dev/null +++ b/rules/elixir-engineer-guidelines-cursorrules-prompt-file/README.md @@ -0,0 +1,37 @@ +# Elixir 工程师指南 .cursorrules 提示文件 + +作者：Zane Riley + +## 您可以构建的内容 +Elixir 微服务平台：开发用于创建和管理微服务的平台，使用 Elixir 语言，利用 Docker 进行容器化，PostgreSQL 进行数据存储。使用 Phoenix LiveView 实现实时数据更新，并通过 Phoenix LiveDashboard 提供监控仪表板。 + +实时协作工具：使用 Elixir 和 Phoenix LiveView 创建 Web 应用程序，允许多个用户同时协作项目。结合 Tailwind CSS 实现现代响应式样式，使用 Ecto 管理 PostgreSQL 中的项目数据。 + +自动化 DevOps 流水线：设计一个 CI/CD 工具，使用 Docker 自动化部署流程，集成 LeftHook 处理 Git 钩子，并使用 Sobelow 和 Credo 扫描代码的安全性和风格问题。利用 ExUnit 进行测试自动化，ExCoveralls 生成测试覆盖率报告。 + +本地化管理系统：构建一个使用 Gettext 管理翻译的系统，让用户能够轻松添加和更新项目的多语言支持。集成文件系统监视器以自动重新加载更改，并提供用户友好的仪表板管理文本。 + +安全通信平台：使用 Elixir 和 Phoenix 开发安全消息应用，整合 Swoosh 发送电子邮件，Finch 处理 HTTP 请求。使用 Sobelow 进行持续安全扫描，Plug 实现自定义中间件集成，确保数据安全。 + +事件监控与响应工具：创建使用 DNS Cluster 进行网络监控和 Phoenix LiveDashboard 提供可视化洞察的警报系统。利用 Ecto 和 PostgreSQL 记录事件数据，Tailwind CSS 增强 UI/UX 设计。 + +基于云的电子商务解决方案：使用 Phoenix LiveView 构建动态产品列表，PostgreSQL 管理交易数据，打造可扩展的电商平台。使用 Docker 简化部署，Swoosh 发送订单确认邮件。 + +交互式学习平台：开发交互式编程教程平台，利用 Phoenix LiveView 提供实时反馈，Ecto 存储练习题。支持 Gettext 多语言翻译，并借助 Tailwind CSS 确保流畅的样式体验。 + +API 管理与网关：使用 Elixir 的 Plug 开发 API 网关解决方案，路由请求，允许开发者设置 API 使用规则，并通过 Phoenix LiveDashboard 监控流量。使用 Finch 处理出站 HTTP 请求，Jason 进行数据序列化。 + +可定制仪表板工具：创建使用 Phoenix LiveDashboard 构建定制仪表板的工具，让用户通过 Ecto 集成指标，并通过 Tailwind CSS 实现可视化。通过 Phoenix LiveView 提供实时数据更新。 + +Q1：如何在使用 Ecto 的分布式 Elixir 服务中管理数据一致性？ +Q2：使用 Phoenix LiveView 构建应用时应考虑哪些安全最佳实践？ +Q3：Docker 如何提升 Elixir 应用的可扩展性？ + +## 优势 + + +## 概要 +使用 Elixir 和 Phoenix 的开发者将通过标准化健壮的提交消息和构建具有全面代码质量与 CI 实践的可扩展、可维护应用而受益。 + +## .cursorrules 提示概述 +.cursorrules 文件概述了专家级高级 Elixir 工程师在使用包含 Elixir、Phoenix、Docker 及其他各种工具和库的技术栈时的指南。它强调在开发前充分考虑代码需求的重要性，以及在响应后提供有见地的后续问题。文件还提供了编写提交消息的结构化方法，详细说明了软件项目中更改的类型、可选范围、描述以及潜在的正文或页脚。这确保了代码更改的清晰性、一致性和正确分类。 diff --git a/rules/elixir-engineer-guidelines-cursorrules-prompt-file/commit-message-format.mdc b/rules/elixir-engineer-guidelines-cursorrules-prompt-file/commit-message-format.mdc new file mode 100644 index 0000000..ab60f28 --- /dev/null +++ b/rules/elixir-engineer-guidelines-cursorrules-prompt-file/commit-message-format.mdc @@ -0,0 +1,22 @@ +--- +description: 将提交消息标准应用于项目中的所有文件。 +globs: **/* +--- +- 使用以下提交消息格式： + <类型>[可选范围]: <描述> + + [可选正文] + + [可选页脚] + + 其中： + + 类型：以下之一：fix（修复）、feat（功能）、build（构建）、chore（杂务）、ci（持续集成）、docs（文档）、perf（性能）、refactor（重构）、revert（回滚）、style（样式）、test（测试） + + 范围（可选）：描述代码库某部分的名词（例如 fluxcd、deployment）。 + + 描述：用现在时态简要总结更改。 + + 正文（可选）：对更改的更详细解释。 + + 页脚（可选）：一个或多个按指定格式的页脚。 diff --git a/rules/engineering-ticket-template-cursorrules-prompt-file/README.md b/rules/engineering-ticket-template-cursorrules-prompt-file/README.md new file mode 100644 index 0000000..58e90f2 --- /dev/null +++ b/rules/engineering-ticket-template-cursorrules-prompt-file/README.md @@ -0,0 +1,35 @@ +# 工程工单模板提示 + +这是一个专门的 .cursorrules 提示，用于创建具有详细需求、实施计划和验收标准的标准化工程工单，以促进开发团队有效协作。 + +## 您可以构建的内容 + +- **结构化工单**：适用于任何任务管理系统的标准化、全面的工程工单 +- **实施路线图**：清晰的分步功能实施指南 +- **验收标准**：以列表或 BDD 格式明确定义的成功标准 +- **技术规范**：详细的技术背景和约束 +- **冲刺规划辅助**：故事点估算和冲刺分配指导 + +## 优势 + +- **清晰的需求**：结构化格式清晰传达需要构建的内容 +- **技术背景**：帮助工程师理解任务的背景信息 +- **实施指导**：提供建议但不过度规定解决方案 +- **冲刺规划**：工作量估算支持敏捷规划流程 +- **跨团队对齐**：连接产品、工程和质量保证视角的格式 +- **减少歧义**：全面的模板最大程度减少澄清问题 + +## 概要 + +此提示帮助技术产品经理创建标准化、全面的工程工单，为开发人员提供理解、实施和测试新功能所需的所有信息，提高效率。 + +## .cursorrules 提示概述 + +.cursorrules 提示指导用户创建有效的工程工单，包含以下关键要素： + +- **灵活格式**：支持列表式和 Given-When-Then 验收标准 +- **完整章节**：包含所有基本工程工单组件的完整模板 +- **详细示例**：使用不同格式的两个全面示例 +- **最佳实践**：编写有效工程工单的十项关键原则 +- **适应性指导**：为不同工具和团队定制工单的建议 +- **平衡性**：在提供足够细节的同时允许技术创造力 diff --git a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/.cursorrules b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/.cursorrules index 137d00f..d91bb25 100644 --- a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/.cursorrules +++ b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/.cursorrules @@ -1,36 +1,35 @@ -you are an expert Angular programmer using TypeScript, Angular 18 and Jest that focuses on producing clear, readable code. +你是一名使用 TypeScript、Angular 18 和 Jest 的 Angular 专家程序员，专注于编写清晰、可读的代码。 -you are thoughtful, give nuanced answers, and are brilliant at reasoning. +你深思熟虑，给出细致入微的答案，并且推理能力卓越。 -you carefully provide accurate, factual, thoughtful answers and are a genius at reasoning. +你仔细提供准确、真实、深思熟虑的答案，并且推理能力超群。 -before providing an answer, think step by step, and provide a detailed, thoughtful answer. +在提供答案之前，请逐步思考，并提供详细、深思熟虑的答案。 -if you need more information, ask for it. +如果你需要更多信息，请提出。 -always write correct, up to date, bug free, fully functional and working code. +始终编写正确、最新、无 bug、功能齐全且可运行的代码。 -focus on performance, readability, and maintainability. +关注性能、可读性和可维护性。 -before providing an answer, double check your work +在提供答案之前，请仔细检查你的工作。 -include all required imports, and ensure proper naming of key components +包含所有必需的导入，并确保关键组件的正确命名。 -do not nest code more than 2 levels deep +代码嵌套深度不超过 2 层。 -prefer using the forNext function, located in libs/smart-ngrx/src/common/for-next.function.ts instead of for(let i;i < length;i++), forEach or for(x of y) +优先使用 `libs/smart-ngrx/src/common/for-next.function.ts` 中的 `forNext` 函数，而不是 `for(let i;i < length;i++)`、`forEach` 或 `for(x of y)`。 -code should obey the rules defined in the .eslintrc.json, .prettierrc, .htmlhintrc, and .editorconfig files +代码应遵守 `.eslintrc.json`、`.prettierrc`、`.htmlhintrc` 和 `.editorconfig` 文件中定义的规则。 -functions and methods should not have more than 4 parameters +函数和方法的参数不应超过 4 个。 -functions should not have more than 50 executable lines +函数的执行行数不应超过 50 行。 -lines should not be more than 80 characters +每行字符数不应超过 80 个。 -when refactoring existing code, keep jsdoc comments intact +重构现有代码时，请保持 JSDoc 注释不变。 -be concise and minimize extraneous prose. - -if you don't know the answer to a request, say so instead of making something up. +言简意赅，尽量减少无关的文字。 +如果你不知道请求的答案，请直接说明，而不是编造。 diff --git a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/README.md b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/README.md index 25195ff..27f1f24 100644 --- a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/README.md +++ b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/README.md @@ -1,16 +1,35 @@ -# Angular TypeScript .cursorrules prompt file +# Angular TypeScript .cursorrules 提示文件 -Author: Dave Bush +作者：Dave Bush -## What you can build -Angular Code Refactoring Tool: A web application that allows developers to input existing Angular code and automatically refactor it according to modern development standards, ensuring compliance with ESLint, Prettier, HTMLHint, and Editorconfig rules.Angular Code Quality Checker: An online service that analyzes Angular code to check for compliance with coding standards, performance issues, readability, and maintainability, providing detailed reports and suggestions for improvement.Angular Best Practices Guide: A comprehensive web-based resource featuring up-to-date best practices for Angular development focusing on TypeScript, including examples and explanations designed to improve code readability, performance, and maintainability.Interactive Angular Workshop Platform: A platform offering interactive workshops and exercises for Angular developers to practice writing clean, readable code using TypeScript, with real-time feedback and code reviews by experts.Angular forNext Utilization Plugin: A plugin for popular IDEs that assists developers in converting traditional loops into the forNext function from libs/smart-ngrx/src/common/for-next.function.ts, improving consistency across projects.Angular Code Formatting Extension: An extension for VS Code that formats Angular code files by following the latest ESLint, Prettier, HTMLHint, and Editorconfig rules, ensuring a uniform code style.AI-Powered Angular Debugging Assistant: A service that integrates into IDEs to provide AI-driven debugging suggestions specifically for Angular projects, helping developers identify and resolve issues efficiently.Angular Performance Optimization Service: An online tool that analyzes Angular applications and suggests performance improvements, focusing on code efficiency, resource loading, and runtime performance enhancements.Angular Codebase Documentation Generator: A tool that automatically generates documentation for Angular projects, maintaining jsdoc comments and updating them to reflect the latest codebase changes, ensuring maintainability.Angular Component Library Analyzer: An application that evaluates custom Angular component libraries for adherence to best practices related to performance, readability, and maintainability, providing audit results and recommended changes. +## 你可以构建什么 -## Benefits +Angular 代码重构工具：一个允许开发人员输入现有 Angular 代码并根据现代开发标准自动重构的 Web 应用程序，确保符合 ESLint、Prettier、HTMLHint 和 Editorconfig 规则。 +Angular 代码质量检查器：一个在线服务，分析 Angular 代码以检查其是否符合编码标准、性能问题、可读性和可维护性，提供详细报告和改进建议。 -## Synopsis -Angular developers aiming to enhance code quality and adhere to best practices can leverage this prompt to build clear, maintainable, and efficient Angular applications using the latest standards and testing with Jest. +Angular 最佳实践指南：一个全面的基于 Web 的资源，提供最新的 Angular 开发最佳实践，重点关注 TypeScript，包括旨在提高代码可读性、性能和可维护性的示例和解释。 -## Overview of .cursorrules prompt -The .cursorrules file specifies guidelines for an expert Angular programmer using TypeScript, Angular 18, and Jest to produce code that is clear, readable, and performant. It emphasizes thoughtful and accurate reasoning, with a focus on providing well-reasoned answers. The file highlights best practices such as writing bug-free and fully functional code, ensuring proper imports and naming, and adhering to specific coding standards from configuration files like .eslintrc.json and .prettierrc. It also sets constraints on code structure and style, including limits on parameter count, lines of code, and nesting depth. The .cursorrules file encourages refactoring while preserving documentation and maintaining conciseness. +交互式 Angular 工作坊平台：一个为 Angular 开发人员提供交互式工作坊和练习的平台，用于练习使用 TypeScript 编写清晰、可读的代码，并由专家提供实时反馈和代码审查。 +Angular forNext 利用插件：一个用于流行 IDE 的插件，帮助开发人员将传统循环转换为 `libs/smart-ngrx/src/common/for-next.function.ts` 中的 `forNext` 函数，从而提高项目之间的一致性。 + +Angular 代码格式化扩展：一个用于 VS Code 的扩展，通过遵循最新的 ESLint、Prettier、HTMLHint 和 Editorconfig 规则来格式化 Angular 代码文件，确保统一的代码风格。 + +AI 驱动的 Angular 调试助手：一个集成到 IDE 中的服务，专门为 Angular 项目提供 AI 驱动的调试建议，帮助开发人员高效识别和解决问题。 + +Angular 性能优化服务：一个在线工具，分析 Angular 应用程序并提出性能改进建议，重点关注代码效率、资源加载和运行时性能增强。 + +Angular 代码库文档生成器：一个自动为 Angular 项目生成文档的工具，维护 jsdoc 注释并更新它们以反映最新的代码库更改，确保可维护性。 + +Angular 组件库分析器：一个评估自定义 Angular 组件库是否符合与性能、可读性和可维护性相关的最佳实践的应用程序，提供审计结果和建议的更改。 + +## 优势 + +## 概要 + +旨在提高代码质量并遵守最佳实践的 Angular 开发人员可以利用此提示来构建清晰、可维护、高效的 Angular 应用程序，使用最新的标准并通过 Jest 进行测试。 + +## .cursorrules 提示概述 + +`.cursorrules` 文件为使用 TypeScript、Angular 18 和 Jest 的 Angular 专家程序员指定了指导方针，以生成清晰、可读且高性能的代码。它强调深思熟虑和准确的推理，重点是提供有充分理由的答案。该文件强调了最佳实践，例如编写无 bug 且功能齐全的代码，确保正确的导入和命名，并遵守来自 `.eslintrc.json` 和 `.prettierrc` 等配置文件的特定编码标准。它还对代码结构和风格设置了约束，包括参数数量、代码行数和嵌套深度的限制。`.cursorrules` 文件鼓励在重构时保留文档并保持简洁。 diff --git a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/angular-general.mdc b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/angular-general.mdc index 8395cab..17ecb03 100644 --- a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/angular-general.mdc +++ b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/angular-general.mdc @@ -1,22 +1,22 @@ --- -description: General rules for Angular components, focusing on code quality, performance, and maintainability. +description: Angular 组件通用规则，侧重于代码质量、性能和可维护性。 globs: **/*.component.ts --- -- You are an expert Angular programmer using TypeScript, Angular 18 and Jest that focuses on producing clear, readable code. -- You are thoughtful, give nuanced answers, and are brilliant at reasoning. -- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning. -- Before providing an answer, think step by step, and provide a detailed, thoughtful answer. -- If you need more information, ask for it. -- Always write correct, up to date, bug free, fully functional and working code. -- Focus on performance, readability, and maintainability. -- Before providing an answer, double check your work. -- Include all required imports, and ensure proper naming of key components. -- Do not nest code more than 2 levels deep. -- Prefer using the forNext function, located in libs/smart-ngrx/src/common/for-next.function.ts instead of for(let i;i < length;i++), forEach or for(x of y). -- Code should obey the rules defined in the .eslintrc.json, .prettierrc, .htmlhintrc, and .editorconfig files. -- Functions and methods should not have more than 4 parameters. -- Functions should not have more than 50 executable lines. -- Lines should not be more than 80 characters. -- When refactoring existing code, keep jsdoc comments intact. -- Be concise and minimize extraneous prose. -- If you don't know the answer to a request, say so instead of making something up. \ No newline at end of file +- 你是一名使用 TypeScript、Angular 18 和 Jest 的 Angular 专家程序员，专注于编写清晰、可读的代码。 +- 你深思熟虑，给出细致入微的答案，并且推理能力卓越。 +- 你仔细提供准确、真实、深思熟虑的答案，并且推理能力超群。 +- 在提供答案之前，请逐步思考，并提供详细、深思熟虑的答案。 +- 如果你需要更多信息，请提出。 +- 始终编写正确、最新、无 bug、功能齐全且可运行的代码。 +- 关注性能、可读性和可维护性。 +- 在提供答案之前，请仔细检查你的工作。 +- 包含所有必需的导入，并确保关键组件的正确命名。 +- 代码嵌套深度不超过 2 层。 +- 优先使用 `libs/smart-ngrx/src/common/for-next.function.ts` 中的 `forNext` 函数，而不是 `for(let i;i < length;i++)`、`forEach` 或 `for(x of y)`。 +- 代码应遵守 `.eslintrc.json`、`.prettierrc`、`.htmlhintrc` 和 `.editorconfig` 文件中定义的规则。 +- 函数和方法的参数不应超过 4 个。 +- 函数的执行行数不应超过 50 行。 +- 每行字符数不应超过 80 个。 +- 重构现有代码时，请保持 JSDoc 注释不变。 +- 言简意赅，尽量减少无关的文字。 +- 如果你不知道请求的答案，请直接说明，而不是编造。 diff --git a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/angular-template-hints.mdc b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/angular-template-hints.mdc index df1c0b3..b385203 100644 --- a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/angular-template-hints.mdc +++ b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/angular-template-hints.mdc @@ -1,6 +1,6 @@ --- -description: Rules specific to Angular templates that ensures code quality standards. +description: 确保代码质量标准的 Angular 模板特定规则。 globs: **/*.component.html --- -- Code should obey the rules defined in the .htmlhintrc, and .editorconfig files. -- Be concise and minimize extraneous prose. \ No newline at end of file +- 代码应遵守 `.htmlhintrc` 和 `.editorconfig` 文件中定义的规则。 +- 言简意赅，尽量减少无关的文字。 diff --git a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/general-reasoning.mdc b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/general-reasoning.mdc index 2d26242..01bdea5 100644 --- a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/general-reasoning.mdc +++ b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/general-reasoning.mdc @@ -1,8 +1,8 @@ --- -description: Rules about reasoning, accuracy, and knowledge gaps +description: 关于推理、准确性和知识空白的规则 globs: **/* --- -- You are thoughtful, give nuanced answers, and are brilliant at reasoning. -- You carefully provide accurate, factual, thoughtful answers and are a genius at reasoning. -- Before providing an answer, think step by step, and provide a detailed, thoughtful answer. -- If you don't know the answer to a request, say so instead of making something up. \ No newline at end of file +- 你深思熟虑，给出细致入微的答案，并且推理能力卓越。 +- 你仔细提供准确、真实、深思熟虑的答案，并且推理能力超群。 +- 在提供答案之前，请逐步思考，并提供详细、深思熟虑的答案。 +- 如果你不知道请求的答案，请直接说明，而不是编造。 diff --git a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/refactoring-existing-code.mdc b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/refactoring-existing-code.mdc index c6b758b..c01c280 100644 --- a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/refactoring-existing-code.mdc +++ b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/refactoring-existing-code.mdc @@ -1,6 +1,6 @@ --- -description: Instructions for refactoring code, focusing on readability, performance, and maintainability. +description: 重构代码的说明，侧重于可读性、性能和可维护性。 globs: **/* --- -- Focus on performance, readability, and maintainability when refactoring existing code. -- When refactoring existing code, keep jsdoc comments intact. \ No newline at end of file +- 在重构现有代码时，请关注性能、可读性和可维护性。 +- 重构现有代码时，请保持 JSDoc 注释不变。 diff --git a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/typescript-coding-style.mdc b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/typescript-coding-style.mdc index a9b613c..0934dc2 100644 --- a/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/typescript-coding-style.mdc +++ b/rules/frontend/angular/angular-typescript-cursorrules-prompt-file/typescript-coding-style.mdc @@ -1,9 +1,9 @@ --- -description: Enforces code style and best practices for TypeScript files. +description: 强制执行 TypeScript 文件的代码风格和最佳实践。 globs: **/*.ts --- -- Code should obey the rules defined in the .eslintrc.json, .prettierrc, and .editorconfig files. -- Lines should not be more than 80 characters. -- Prefer using the forNext function, located in libs/smart-ngrx/src/common/for-next.function.ts instead of for(let i;i < length;i++), forEach or for(x of y). -- Functions and methods should not have more than 4 parameters. -- Functions should not have more than 50 executable lines. \ No newline at end of file +- 代码应遵守 `.eslintrc.json`、`.prettierrc` 和 `.editorconfig` 文件中定义的规则。 +- 每行字符数不应超过 80 个。 +- 优先使用 `libs/smart-ngrx/src/common/for-next.function.ts` 中的 `forNext` 函数，而不是 `for(let i;i < length;i++)`、`forEach` 或 `for(x of y)`。 +- 函数和方法的参数不应超过 4 个。 +- 函数的执行行数不应超过 50 行。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---complex-state-management.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---complex-state-management.mdc index a2b6bbc..5ef80a5 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---complex-state-management.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---complex-state-management.mdc @@ -1,8 +1,159 @@ --- -description: -globs: +description: SolidJS 复杂状态管理 +globs: [] alwaysApply: false --- +# SolidJS 复杂状态管理 +本规则集定义了在 SolidJS 应用程序中处理复杂状态管理的策略和最佳实践，旨在确保状态的可预测性、可维护性和高性能。 +## 1. 状态管理核心概念 + +SolidJS 的核心是其细粒度响应系统，这使得状态管理相对直接。对于复杂场景，可以结合使用以下模式： + +- **信号 (Signals)**: SolidJS 的基本响应式原语，用于存储和更新状态。 +- **派生状态 (Derived State)**: 通过 `createMemo` 从现有信号计算出的值，只有当其依赖项改变时才重新计算。 +- **存储 (Stores)**: 用于管理复杂对象或嵌套状态，通常通过 `createStore` 创建。 + +## 2. 组织复杂状态 + +### 2.1 模块化状态 + +将相关状态和操作封装在独立的模块或文件中，提高代码组织性。 + +```javascript +// stores/auth.js +import { createSignal } from 'solid-js'; + +const [user, setUser] = createSignal(null); +const [isAuthenticated, setIsAuthenticated] = createSignal(false); + +export const authStore = { + user, + isAuthenticated, + login: (userData) => { + setUser(userData); + setIsAuthenticated(true); + }, + logout: () => { + setUser(null); + setIsAuthenticated(false); + }, +}; +``` + +### 2.2 扁平化嵌套状态 (使用 `createStore`) + +对于嵌套对象或数组，`createStore` 可以提供细粒度的更新，避免不必要的重新渲染。 + +```javascript +import { createStore } from 'solid-js/store'; + +const [state, setState] = createStore({ + user: { name: 'John', age: 30 }, + settings: { theme: 'dark', notifications: true }, + items: [{ id: 1, name: 'Item A' }, { id: 2, name: 'Item B' }], +}); + +// 更新嵌套属性 +setState('user', 'age', a => a + 1); +// 更新数组中的元素 +setState('items', item => item.id === 1, 'name', 'Updated Item A'); +``` + +## 3. 跨组件状态共享 + +### 3.1 Context API + +对于需要跨多层组件共享的状态，使用 SolidJS 的 Context API 是一个推荐的方式。 + +```javascript +// contexts/ThemeContext.jsx +import { createContext, useContext } from 'solid-js'; +import { createSignal } from 'solid-js'; + +const ThemeContext = createContext(); + +export function ThemeProvider(props) { + const [theme, setTheme] = createSignal('light'); + const toggleTheme = () => setTheme(t => (t === 'light' ? 'dark' : 'light')); + + return ( + + {props.children} + + ); +} + +export function useTheme() { + return useContext(ThemeContext); +} + +// Usage in a component: +// import { useTheme } from '../contexts/ThemeContext'; +// const { theme, toggleTheme } = useTheme(); +``` + +### 3.2 全局存储 (Global Stores) + +对于应用程序级别的全局状态，可以直接从模块导出信号或存储，并在任何需要的地方导入使用。这适用于不需要 Context API 提供的层级结构的场景。 + +```javascript +// stores/globalCounter.js +import { createSignal } from 'solid-js'; + +export const [count, setCount] = createSignal(0); + +// components/MyComponent.jsx +import { count, setCount } from '../stores/globalCounter'; + +function MyComponent() { + return ( +
    +

    Count: {count()}

    + +
    + ); +} +``` + +## 4. 异步状态管理 + +对于异步数据，可以使用 `createResource` 或结合 `createSignal` 和 `createEffect` 来管理加载状态、错误和数据。 + +```javascript +import { createResource, createSignal, onMount } from 'solid-js'; + +async function fetchUser(id) { + const response = await fetch(`/api/users/${id}`); + return response.json(); +} + +function UserProfile(props) { + const [userId, setUserId] = createSignal(props.id); + const [user] = createResource(userId, fetchUser); + + return ( +
    + +

    Loading user...

    +     + +

    Error: {user.error.message}

    +     + +

    User Name: {user().name}

    +     +
    + ); +} +``` + +## 5. 最佳实践 + +- **最小化状态**: 仅将真正需要响应式更新的数据存储为信号或存储。 +- **避免不必要的响应性**: 对于不需要响应式的数据，使用普通变量。 +- **单一职责原则**: 确保每个信号或存储管理一个单一的、内聚的状态片段。 +- **使用 `createMemo` 优化派生状态**: 避免在模板中直接进行复杂计算，使用 `createMemo` 缓存计算结果。 +- **清晰的命名**: 信号和存储的命名应清晰地反映其内容和用途。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---conditional-and-list-rendering.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---conditional-and-list-rendering.mdc index a2b6bbc..a0ee0cc 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---conditional-and-list-rendering.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---conditional-and-list-rendering.mdc @@ -1,8 +1,146 @@ --- -description: -globs: +description: SolidJS 条件渲染和列表渲染 +globs: [] alwaysApply: false --- +# SolidJS 条件渲染和列表渲染 +本规则集定义了在 SolidJS 应用程序中实现条件渲染和列表渲染的最佳实践，旨在确保高效的 UI 更新和可读的代码结构。 +## 1. 条件渲染 + +SolidJS 处理条件渲染的方式与 React 等其他库有所不同，它利用其细粒度响应式系统，只更新实际改变的部分。 + +### 1.1 使用 `Show` 组件 + +对于简单的条件渲染，可以使用 SolidJS 内置的 `Show` 组件。它接受一个 `when` 属性（一个信号或计算属性），当 `when` 为真时渲染其 `children`，否则渲染 `fallback`。 + +```jsx +import { createSignal, Show } from 'solid-js'; + +function ConditionalDisplay() { + const [loggedIn, setLoggedIn] = createSignal(false); + + return ( +
    + setLoggedIn(true)}>Login} + > +

    Welcome, User!

    + +     +
    + ); +} +``` + +### 1.2 使用 `Switch` 和 `Match` 组件 + +对于多个条件的复杂场景，可以使用 `Switch` 和 `Match` 组件，类似于其他语言中的 `switch` 语句。 + +```jsx +import { createSignal, Switch, Match } from 'solid-js'; + +function MultiConditionalDisplay() { + const [status, setStatus] = createSignal('loading'); + + return ( +
    + Unknown Status

    }> + +

    Loading data...

    +     + +

    Data loaded successfully!

    +     + +

    Error loading data.

    +     +     + + + +
    + ); +} +``` + +### 1.3 短路逻辑 (不推荐用于复杂场景) + +虽然可以使用 `&&` 或 `||` 进行短路逻辑渲染，但对于更复杂的条件，推荐使用 `Show` 或 `Switch/Match`，因为它们能更好地利用 SolidJS 的响应式特性，避免不必要的重新创建 DOM 元素。 + +```jsx +// 简单场景可用，复杂场景不推荐 +function SimpleConditional() { + const [isVisible, setIsVisible] = createSignal(true); + return ( +
    + {isVisible() &&

    This is visible.

    } + +
    + ); +} +``` + +## 2. 列表渲染 + +SolidJS 的列表渲染通过 `For` 组件实现，它提供了高效的键控 (keyed) 列表渲染，类似于 React 的 `map` 结合 `key`。 + +### 2.1 使用 `For` 组件 + +`For` 组件接受一个 `each` 属性（一个数组信号或计算属性），并为数组中的每个项渲染其 `children`。`key` 属性是可选的，但强烈推荐提供一个稳定且唯一的 `key`，以优化列表更新性能。 + +```jsx +import { createSignal, For } from 'solid-js'; + +function TodoList() { + const [todos, setTodos] = createSignal([ + { id: 1, text: 'Learn SolidJS', completed: false }, + { id: 2, text: 'Build an App', completed: false }, + ]); + + const addTodo = () => { + const newTodo = { id: todos().length + 1, text: 'New Todo', completed: false }; + setTodos([...todos(), newTodo]); + }; + + return ( +
    + +
      + No todos yet!

      }> + {(todo, i) => ( +
    • + {todo.text} - {todo.completed ? 'Done' : 'Pending'} +
      • + )} +       +
    +
    + ); +} +``` + +### 2.2 键控列表 (Keyed Lists) + +`For` 组件默认使用索引作为 `key`，但这在列表项顺序改变或有增删时会导致性能问题和不正确的行为。因此，始终为 `For` 组件提供一个稳定的、唯一的 `key`。 + +```jsx +// 推荐使用唯一的 ID 作为 key +No todos yet!

    }> + {(todo) =>
  • {todo.text}
    • } +     +``` + +### 2.3 避免在 `For` 循环中创建信号 + +在 `For` 循环内部直接创建信号会导致性能问题，因为每次列表更新时都会重新创建信号。如果需要响应式地处理列表项的内部状态，应将列表项封装到独立的组件中，并在该组件内部管理其状态。 + +## 3. 最佳实践 + +- **优先使用内置组件**: 对于条件渲染和列表渲染，优先使用 SolidJS 提供的 `Show`、`Switch/Match` 和 `For` 组件。 +- **提供唯一的 `key`**: 在 `For` 组件中始终提供一个稳定的、唯一的 `key`。 +- **避免短路逻辑的滥用**: 避免在复杂场景下使用 `&&` 或 `||` 进行条件渲染。 +- **封装列表项**: 如果列表项有自己的内部状态或复杂逻辑，将其封装到独立的组件中。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---data-fetching.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---data-fetching.mdc index a2b6bbc..b26ff02 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---data-fetching.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---data-fetching.mdc @@ -1,8 +1,148 @@ --- -description: -globs: +description: SolidJS 数据获取 +globs: [] alwaysApply: false --- +# SolidJS 数据获取 +本规则集定义了在 SolidJS 应用程序中进行数据获取的策略和最佳实践，旨在确保高效、响应式和可维护的数据流。 +## 1. 使用 `createResource` (推荐) + +`createResource` 是 SolidJS 提供的一个强大且声明式的数据获取原语。它能够自动处理加载状态、错误以及数据的缓存和重新获取，非常适合异步数据源。 + +```javascript +import { createResource, createSignal, Show } from 'solid-js'; + +// 模拟一个异步数据获取函数 +async function fetchUser(userId) { + if (!userId) return undefined; // 当 userId 为 undefined 时不执行请求 + console.log(`Fetching user ${userId}...`); + const response = await new Promise(resolve => setTimeout(() => { + resolve({ id: userId, name: `User ${userId}`, email: `user${userId}@example.com` }); + }, 1000)); + return response; +} + +function UserProfile(props) { + const [userId, setUserId] = createSignal(props.initialUserId); + // createResource 的第一个参数是源信号，当它改变时会触发重新获取 + // 第二个参数是数据获取函数 + const [user] = createResource(userId, fetchUser); + + return ( +
    +

    User Profile

    + setUserId(parseInt(e.target.value) || undefined)} + placeholder="Enter User ID" + /> + +

    Loading user data...

    +     + +

    Error: {user.error.message}

    +     + +

    ID: {user().id}

    +

    Name: {user().name}

    +

    Email: {user().email}

    +     + +

    Please enter a User ID to fetch data.

    +     +
    + ); +} +``` + +### `createResource` 的优势 + +- **自动加载状态**: `resource.loading` 信号自动指示数据是否正在加载。 +- **自动错误处理**: `resource.error` 信号捕获数据获取过程中的错误。 +- **缓存**: `createResource` 会缓存结果，避免重复请求相同的数据。 +- **响应式触发**: 当源信号改变时，自动重新执行数据获取函数。 +- **暂停/恢复**: 可以通过将源信号设置为 `undefined` 或 `null` 来暂停数据获取。 + +## 2. 使用 `createEffect` 进行手动数据获取 + +对于更复杂的场景，或者当 `createResource` 不完全满足需求时，可以使用 `createEffect` 结合 `createSignal` 手动管理数据获取的生命周期。 + +```javascript +import { createSignal, createEffect, onCleanup, Show } from 'solid-js'; + +function ManualDataFetcher(props) { + const [data, setData] = createSignal(null); + const [loading, setLoading] = createSignal(false); + const [error, setError] = createSignal(null); + + createEffect(() => { + const id = props.itemId; + if (!id) return; // 如果没有 ID，则不执行获取 + + setLoading(true); + setError(null); + setData(null); + + const abortController = new AbortController(); + const signal = abortController.signal; + + fetch(`/api/items/${id}`, { signal }) + .then(response => { + if (!response.ok) { + throw new Error(`HTTP error! status: ${response.status}`); + } + return response.json(); + }) + .then(fetchedData => { + setData(fetchedData); + }) + .catch(err => { + if (err.name !== 'AbortError') { + setError(err); + } + }) + .finally(() => { + setLoading(false); + }); + + // 清理函数，当 effect 重新运行时或组件卸载时执行 + onCleanup(() => { + abortController.abort(); // 取消正在进行的请求 + }); + }); + + return ( +
    +

    Manual Data Fetcher

    + +

    Loading item...

    +     + +

    Error: {error().message}

    +     + +

    Item Name: {data().name}

    +

    Description: {data().description}

    +     +
    + ); +} +``` + +### 适用场景 + +- 需要更精细控制请求生命周期（如取消请求）时。 +- 数据获取逻辑非常复杂，需要自定义处理流程时。 + +## 3. 最佳实践 + +- **优先使用 `createResource`**: 它是 SolidJS 官方推荐的数据获取方式，能处理大多数场景，并提供开箱即用的加载/错误状态管理。 +- **处理加载和错误状态**: 始终在 UI 中反映数据的加载状态和任何可能发生的错误，提供良好的用户体验。 +- **数据源信号化**: 将触发数据获取的参数（如 ID、查询字符串）封装为信号，以便 `createResource` 能够响应式地重新获取数据。 +- **避免在模板中直接进行数据获取**: 数据获取逻辑应封装在组件外部的函数或 `createResource`/`createEffect` 中。 +- **取消未完成的请求**: 在组件卸载或数据源信号改变时，取消之前未完成的请求，避免内存泄漏和不必要的网络活动。 +- **服务端渲染 (SSR) 考虑**: 如果使用 SSR，`createResource` 也能很好地工作，因为它支持在服务器端预取数据。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---derived-values-management.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---derived-values-management.mdc index a2b6bbc..708ef2c 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---derived-values-management.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---derived-values-management.mdc @@ -1,8 +1,111 @@ --- -description: -globs: +description: SolidJS 派生值管理 +globs: [] alwaysApply: false --- +# SolidJS 派生值管理 +本规则集定义了在 SolidJS 应用程序中如何高效地管理派生值（Derived Values），旨在确保计算的最小化、响应式更新的精确性以及代码的清晰度。 +## 1. 什么是派生值？ + +派生值是指那些不是直接存储在信号中，而是通过其他响应式数据（如信号、存储、其他派生值）计算得出的值。当其依赖的响应式数据发生变化时，派生值会自动重新计算。 + +## 2. 使用 `createMemo` (推荐) + +`createMemo` 是 SolidJS 中用于创建派生值的核心原语。它类似于 React 的 `useMemo` 或 Vue 的计算属性，但 SolidJS 的 `createMemo` 具有更细粒度的响应式更新，只有当其依赖项实际发生变化时才会重新计算。 + +```javascript +import { createSignal, createMemo } from 'solid-js'; + +function Counter() { + const [count, setCount] = createSignal(0); + const [multiplier, setMultiplier] = createSignal(2); + + // 派生值：计算 count * multiplier + const multipliedCount = createMemo(() => count() * multiplier()); + + return ( +
    +

    Count: {count()}

    +

    Multiplier: {multiplier()}

    +

    Multiplied Count: {multipliedCount()}

    + + +
    + ); +} +``` + +### `createMemo` 的优势 + +- **惰性计算**: `createMemo` 只有当其值被读取时才会执行计算函数。 +- **缓存结果**: 只有当依赖项发生变化时，`createMemo` 才会重新计算其值，否则返回缓存的结果，避免不必要的重复计算。 +- **细粒度更新**: SolidJS 的编译器会优化 `createMemo` 的依赖追踪，确保只有真正需要更新的视图部分才会重新渲染。 + +## 3. 避免在 JSX 中直接进行复杂计算 + +虽然可以在 JSX 模板中直接进行简单的计算，但对于复杂的计算或需要缓存结果的计算，应始终使用 `createMemo`。在 JSX 中直接进行复杂计算会导致每次组件重新渲染时都重复执行，降低性能。 + +```javascript +// 不推荐：在 JSX 中直接进行复杂计算 +function BadExample() { + const [items, setItems] = createSignal([{ price: 10, quantity: 2 }, { price: 5, quantity: 3 }]); + + return ( +
    +

    Total: {items().reduce((sum, item) => sum + item.price * item.quantity, 0)}

    +
    + ); +} + +// 推荐：使用 createMemo 计算派生值 +function GoodExample() { + const [items, setItems] = createSignal([{ price: 10, quantity: 2 }, { price: 5, quantity: 3 }]); + + const total = createMemo(() => items().reduce((sum, item) => sum + item.price * item.quantity, 0)); + + return ( +
    +

    Total: {total()}

    +
    + ); +} +``` + +## 4. 派生值与副作用 (Effects) + +`createMemo` 用于计算值，而 `createEffect` 用于执行副作用（如 DOM 操作、日志记录、订阅外部服务）。不要在 `createMemo` 中执行副作用，也不要依赖于 `createEffect` 的返回值。 + +```javascript +import { createSignal, createMemo, createEffect } from 'solid-js'; + +function SideEffectExample() { + const [firstName, setFirstName] = createSignal("John"); + const [lastName, setLastName] = createSignal("Doe"); + + // 派生值：全名 + const fullName = createMemo(() => `${firstName()} ${lastName()}`); + + // 副作用：当 fullName 改变时打印日志 + createEffect(() => { + console.log(`Full Name changed to: ${fullName()}`); + }); + + return ( +
    + setFirstName(e.target.value)} /> + setLastName(e.target.value)} /> +

    Hello, {fullName()}

    +
    + ); +} +``` + +## 5. 最佳实践 + +- **始终使用 `createMemo`**: 对于任何从现有响应式数据计算得出的值，都应该使用 `createMemo` 来创建，以确保性能和正确性。 +- **避免循环依赖**: 确保 `createMemo` 的计算函数不会直接或间接依赖于其自身的值，这会导致无限循环。 +- **清晰的命名**: 派生值的命名应清晰地反映其计算逻辑和用途。 +- **分离计算与副作用**: 严格区分 `createMemo`（计算值）和 `createEffect`（执行副作用）的职责。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---error-boundaries.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---error-boundaries.mdc index a2b6bbc..037212a 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---error-boundaries.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---error-boundaries.mdc @@ -1,8 +1,97 @@ --- -description: -globs: +description: SolidJS 错误边界 +globs: [] alwaysApply: false --- +# SolidJS 错误边界 +本规则集定义了在 SolidJS 应用程序中如何实现错误边界（Error Boundaries），以优雅地捕获组件树中的 JavaScript 错误，并显示备用 UI，而不是导致整个应用程序崩溃。 +## 1. 什么是错误边界？ + +错误边界是一种 SolidJS 组件，它可以捕获其子组件树中任何位置的 JavaScript 错误，记录这些错误，并显示一个备用 UI，而不是崩溃整个组件树。错误边界在渲染期间、生命周期方法中以及构造函数中捕获错误。 + +## 2. SolidJS 中的错误边界 + +SolidJS 本身没有像 React 那样内置的 `componentDidCatch` 或 `getDerivedStateFromError` 生命周期方法。然而，可以通过 `createEffect` 和 `onError` 回调函数来模拟错误边界的行为。 + +### 2.1 使用 `onError` 回调 + +`onError` 是 SolidJS 提供的一个回调函数，它可以在组件内部或组件树的任何地方捕获渲染或更新过程中的错误。当错误发生时，`onError` 会被调用，并且可以用来更新本地状态以显示回退 UI。 + +```javascript +import { createSignal, onError, Show } from 'solid-js'; + +function ErrorBoundary(props) { + const [error, setError] = createSignal(null); + + // 捕获子组件树中的错误 + onError((err) => { + console.error("Caught an error:", err); + setError(err); + }); + + return ( + +

    Something went wrong.

    +

    Error details: {error()?.message}

    + +
    + } + > + {props.children} + + ); +} + +function BuggyComponent() { + const [count, setCount] = createSignal(0); + + const handleClick = () => { + setCount(c => c + 1); + if (count() === 2) { + throw new Error("I crashed at count 2!"); + } + }; + + return ( +
    +

    Count: {count()}

    + +
    + ); +} + +function App() { + return ( +
    +

    My App

    + + + +

    This part of the app is still working.

    +
    + ); +} +``` + +### 2.2 错误边界的放置 + +错误边界应该放置在您希望捕获错误并显示备用 UI 的组件树的任何位置。通常，您会将其放置在路由组件的顶层，或者在可能包含不稳定组件的 UI 部分周围。 + +## 3. 最佳实践 + +- **细化错误边界范围**: 不要将整个应用程序包裹在一个错误边界中。这会使得错误难以定位，并且可能隐藏其他部分的问题。将错误边界放置在逻辑上独立的 UI 块周围。 +- **提供有用的回退 UI**: 当错误发生时，显示一个清晰、友好的消息，告知用户发生了什么，并提供可能的解决方案（如“刷新页面”或“联系支持”）。 +- **记录错误**: 在错误边界中捕获到错误时，务必将其记录到日志服务（如 Sentry、Bugsnag）中，以便开发人员可以及时发现并修复问题。 +- **避免在错误边界内部抛出错误**: 错误边界本身不应该抛出错误，否则它将无法捕获自身的错误。 +- **测试错误边界**: 编写测试用例来验证错误边界是否按预期工作，包括它是否捕获错误、是否显示正确的备用 UI 以及是否正确记录错误。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---functional-components-preference.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---functional-components-preference.mdc index a2b6bbc..6270f78 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---functional-components-preference.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---functional-components-preference.mdc @@ -1,8 +1,91 @@ --- -description: -globs: +description: SolidJS 函数式组件偏好 +globs: [] alwaysApply: false --- +# SolidJS 函数式组件偏好 +本规则集定义了在 SolidJS 应用程序中优先使用函数式组件的实践，旨在促进代码的简洁性、可重用性和响应式更新的效率。 +## 1. 函数式组件的核心 + +在 SolidJS 中，组件本质上是普通的 JavaScript 函数，它们在渲染时只运行一次。响应式更新不是通过重新运行组件函数来实现的，而是通过 SolidJS 的细粒度响应式系统直接更新 DOM。 + +```javascript +// 这是一个简单的 SolidJS 函数式组件 +function MyComponent(props) { + return ( +
    +

    Hello, {props.name}!

    +
    + ); +} + +// 在其他组件中使用 +function App() { + return ; +} +``` + +## 2. 为什么偏好函数式组件？ + +- **性能优化**: SolidJS 的函数式组件只在初始化时执行一次，而不是像 React 那样在每次状态更新时重新渲染。这意味着更少的 JavaScript 执行，更高的性能。 +- **简洁性**: 代码更少，逻辑更直接，没有类组件中的 `this` 绑定问题或复杂的生命周期方法。 +- **响应式直观**: 响应式数据（信号、存储）可以直接在组件函数中使用，SolidJS 会自动追踪依赖并更新受影响的 DOM 部分。 +- **可重用性**: 函数式组件更容易被抽象和重用，因为它们只是纯函数，接受 `props` 并返回 JSX。 + +## 3. 状态管理与副作用 + +在函数式组件中，状态管理和副作用通过 SolidJS 提供的原语（如 `createSignal`, `createEffect`, `createMemo`, `createResource`）来处理。 + +### 3.1 信号 (Signals) + +用于管理组件的局部状态。 + +```javascript +import { createSignal } from 'solid-js'; + +function Counter() { + const [count, setCount] = createSignal(0); + + return ( +
    +

    Count: {count()}

    + +
    + ); +} +``` + +### 3.2 副作用 (Effects) + +使用 `createEffect` 处理需要响应式地执行的副作用，例如日志记录、订阅外部数据等。 + +```javascript +import { createSignal, createEffect } from 'solid-js'; + +function Logger() { + const [value, setValue] = createSignal("initial"); + + createEffect(() => { + console.log("Value changed:", value()); + }); + + return ( + setValue(e.target.value)} + /> + ); +} +``` + +## 4. 最佳实践 + +- **保持组件精简**: 尽量让函数式组件只负责渲染 UI，将复杂逻辑（如数据获取、状态管理）抽离到自定义 Hooks 或独立的模块中。 +- **使用 `props` 传递数据**: 通过 `props` 将数据从父组件传递给子组件。如果 `props` 是响应式的（例如，来自信号），SolidJS 会自动处理更新。 +- **避免在组件函数顶层执行昂贵操作**: 由于组件函数只运行一次，如果其中有昂贵的操作，它只会在组件挂载时执行。但如果操作依赖于响应式数据，请将其包裹在 `createMemo` 或 `createEffect` 中。 +- **利用 SolidJS 原语**: 充分利用 `createSignal`, `createEffect`, `createMemo`, `createResource` 等 SolidJS 提供的响应式原语来管理状态和逻辑。 +- **清晰的组件职责**: 每个函数式组件都应该有一个清晰的职责，避免一个组件承担过多的功能。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---jsx-templates.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---jsx-templates.mdc index a2b6bbc..09adda2 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---jsx-templates.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---jsx-templates.mdc @@ -1,8 +1,125 @@ --- -description: -globs: +description: SolidJS JSX 模板 +globs: [] alwaysApply: false --- +# SolidJS JSX 模板 +本规则集定义了在 SolidJS 应用程序中使用 JSX 模板的策略和最佳实践，旨在确保代码的清晰度、可维护性以及与 SolidJS 响应式系统的无缝集成。 +## 1. JSX 基础 + +SolidJS 使用 JSX 作为其模板语言，与 React 类似，但其内部工作方式有所不同。在 SolidJS 中，JSX 被编译为真实的 DOM 操作，而不是虚拟 DOM。这意味着 JSX 表达式只运行一次，而其中的响应式数据更新会直接、细粒度地反映到 DOM 上。 + +```jsx +import { createSignal } from 'solid-js'; + +function Greeting() { + const [name, setName] = createSignal("World"); + + return ( +
    +

    Hello, {name()}!

    + setName(e.target.value)} + /> +
    + ); +} +``` + +## 2. 响应式表达式 + +在 JSX 中，任何包含信号或计算属性的表达式都应该是函数调用形式（例如 `name()`），这样 SolidJS 才能追踪其依赖并在值变化时更新相应的 DOM 部分。 + +```jsx +// 正确：使用函数调用来访问信号的值 +

    Count: {count()}

    + +// 错误：直接访问信号，这将不会响应式更新 +//

    Count: {count}

    +``` + +## 3. 属性绑定 + +### 3.1 静态属性 + +静态属性直接写在 JSX 元素上。 + +```jsx +
    Static Content
    +``` + +### 3.2 动态属性 + +动态属性使用花括号 `{}` 包裹 JavaScript 表达式。对于布尔属性，如果值为 `true`，属性会被添加；如果为 `false` 或 `null`，属性会被移除。 + +```jsx + +Dynamic Image +``` + +### 3.3 class 和 style + +- **`class`**: 可以是字符串、对象或数组。对象形式的键是类名，值是布尔值，用于条件性地添加类。 + + ```jsx +
    + Dynamic Classes +
    + ``` + +- **`style`**: 可以是字符串或对象。对象形式的键是 CSS 属性名（驼峰命名），值是属性值。 + + ```jsx +
    + Dynamic Styles +
    + ``` + +## 4. 条件渲染和列表渲染 + +SolidJS 提供了专门的控制流组件 (`Show`, `Switch`, `For`) 来处理条件渲染和列表渲染，这些组件是优化性能和响应式更新的关键。 + +### 4.1 条件渲染 (`Show`, `Switch/Match`) + +```jsx +import { Show, Switch, Match } from 'solid-js'; + +Welcome, {user().name}! + +Loading...

    }> + Data Loaded! + Error! +     +``` + +### 4.2 列表渲染 (`For`) + +```jsx +import { For } from 'solid-js'; + + + {(item) =>
  • {item.name}
    • } +     +``` + +## 5. 事件处理 + +事件处理与 React 类似，使用 `on` 前缀的驼峰命名属性，值为一个函数。 + +```jsx + + setValue(e.target.value)} /> +``` + +## 6. 最佳实践 + +- **保持 JSX 简洁**: JSX 应该主要用于描述 UI 结构，将复杂的逻辑（如数据转换、条件判断）移到组件函数或 `createMemo` 中。 +- **使用控制流组件**: 始终优先使用 SolidJS 提供的 `Show`, `Switch`, `For` 等控制流组件进行条件和列表渲染，而不是在 JSX 中使用 JavaScript 逻辑运算符。 +- **正确访问响应式值**: 确保所有响应式值（信号、存储、计算属性）在 JSX 中都以函数调用的形式访问。 +- **提供 `key` 属性**: 在列表渲染时，为 `For` 组件的子元素提供一个稳定且唯一的 `key` 属性，以优化性能。 +- **避免不必要的重新渲染**: SolidJS 已经非常优化，但仍需注意避免在 JSX 中创建不必要的响应式依赖或执行昂贵的操作。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---lazy-loading.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---lazy-loading.mdc index a2b6bbc..008beca 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---lazy-loading.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---lazy-loading.mdc @@ -1,8 +1,120 @@ --- -description: -globs: +description: SolidJS 懒加载 +globs: [] alwaysApply: false --- +# SolidJS 懒加载 +本规则集定义了在 SolidJS 应用程序中实现组件和路由懒加载的策略和最佳实践，旨在优化应用程序的初始加载时间，提升用户体验。 +## 1. 什么是懒加载？ + +懒加载（Lazy Loading），也称为代码分割（Code Splitting），是一种优化技术，它允许您只在需要时才加载应用程序的某些部分。这对于大型应用程序尤其有用，因为它可以显著减少初始加载时下载的 JavaScript 包大小。 + +## 2. SolidJS 中的组件懒加载 + +SolidJS 通过 `lazy` 函数和 `Suspense` 组件来支持组件的懒加载，这与 React 的 `React.lazy` 和 `Suspense` 类似。 + +### 2.1 使用 `lazy` 函数 + +`lazy` 函数接受一个返回 `Promise` 的函数，该 `Promise` 最终解析为一个 SolidJS 组件。通常，这个 `Promise` 会通过动态 `import()` 来实现。 + +```javascript +import { lazy } from 'solid-js'; + +// 懒加载 MyLazyComponent +const MyLazyComponent = lazy(() => import('./MyLazyComponent')); +``` + +### 2.2 使用 `Suspense` 组件 + +`Suspense` 组件用于包裹懒加载的组件。当懒加载组件正在加载时，`Suspense` 会渲染其 `fallback` 属性提供的内容。一旦组件加载完成，`fallback` 内容就会被替换为实际组件。 + +```jsx +import { lazy, Suspense } from 'solid-js'; + +const MyLazyComponent = lazy(() => import('./MyLazyComponent')); + +function App() { + return ( +
    +

    Welcome to My App

    + Loading MyLazyComponent...
    }> + + + + ); +} +``` + +### 2.3 错误处理 + +如果懒加载的组件加载失败（例如，网络错误），`Suspense` 不会捕获这个错误。您需要使用错误边界（Error Boundaries）来处理这类错误。 + +## 3. Solid Router 中的路由懒加载 + +当使用 Solid Router 进行路由管理时，也可以结合 `lazy` 和 `Suspense` 实现路由级别的代码分割。 + +```jsx +import { lazy, Suspense } from 'solid-js'; +import { useRoutes } from '@solidjs/router'; + +// 懒加载路由组件 +const Home = lazy(() => import('./pages/Home')); +const About = lazy(() => import('./pages/About')); +const Contact = lazy(() => import('./pages/Contact')); + +const AppRoutes = () => { + const routes = useRoutes([ + { + path: '/', + component: () => ( + Loading Home...}> + + + ), + }, + { + path: '/about', + component: () => ( + Loading About...}> + + + ), + }, + { + path: '/contact', + component: () => ( + Loading Contact...}> + + + ), + }, + ]); + + return routes; +}; + +function App() { + return ( + <> + + + + ); +} +``` + +## 4. 最佳实践 + +- **识别可懒加载的模块**: 通常，路由组件、大型库、不经常使用的功能模块是懒加载的理想候选者。 +- **提供有意义的 `fallback`**: 在组件加载期间，向用户显示有意义的加载指示器（例如，骨架屏、加载动画），而不是空白页面。 +- **结合错误边界**: 始终将懒加载的组件包裹在错误边界中，以优雅地处理加载失败的情况。 +- **避免过度分割**: 过度细粒度的代码分割可能会导致过多的网络请求，反而影响性能。找到一个平衡点。 +- **预加载 (Preloading)**: 对于用户可能很快会访问的路由或组件，可以考虑使用预加载技术，在空闲时间提前加载它们，进一步提升用户体验。 +- **SSR 兼容性**: 确保您的懒加载策略与服务端渲染 (SSR) 兼容，如果您的应用程序使用了 SSR。 diff --git a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---naming-conventions.mdc b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---naming-conventions.mdc index a2b6bbc..c1f1bcd 100644 --- a/rules/frontend/solidjs/solidjs-basic-guide/solidjs---naming-conventions.mdc +++ b/rules/frontend/solidjs/solidjs-basic-guide/solidjs---naming-conventions.mdc @@ -1,8 +1,70 @@ --- -description: -globs: +description: SolidJS 命名约定 +globs: [] alwaysApply: false --- +# SolidJS 命名约定 +本规则集定义了在 SolidJS 应用程序中推荐的命名约定，旨在提高代码的可读性、一致性和可维护性，使团队协作更加顺畅。 +## 1. 文件命名 + +- **组件文件**: 使用 PascalCase（大驼峰命名法）命名组件文件，并以 `.jsx` 或 `.tsx` 扩展名结尾。 + - 示例: `UserProfile.jsx`, `Button.tsx` +- **Hooks/工具函数文件**: 使用 kebab-case（烤串命名法）或 snake_case（蛇形命名法）命名，并清晰地表明其用途。 + - 示例: `use-auth.js`, `data_utils.ts` +- **样式文件**: 与组件文件同名，并使用相应的样式扩展名（如 `.css`, `.module.css`, `.scss`）。 + - 示例: `UserProfile.module.css` +- **常量文件**: 使用 kebab-case 或 snake_case，通常放在 `constants` 目录下。 + - 示例: `app-constants.js`, `api_endpoints.ts` + +## 2. 组件命名 + +- **组件名称**: 始终使用 PascalCase（大驼峰命名法）。组件名称应该清晰、描述性强，并反映其功能。 + - 示例: `Header`, `ProductCard`, `UserAvatar` +- **避免通用名称**: 避免使用过于通用的名称，如 `Component`, `Item`，除非它们在特定上下文中非常明确。 + +## 3. 信号 (Signals) 和存储 (Stores) 命名 + +- **信号**: 使用 `createSignal` 创建的信号，通常使用 `[value, setValue]` 的解构形式。`value` 部分使用 camelCase（小驼峰命名法）。 + - 示例: `const [count, setCount] = createSignal(0);` + - 对于布尔值，通常以 `is` 或 `has` 开头。 + - 示例: `const [isLoading, setIsLoading] = createSignal(false);` +- **存储**: 使用 `createStore` 创建的存储，通常使用 `[state, setState]` 的解构形式。`state` 部分使用 camelCase。 + - 示例: `const [userStore, setUserStore] = createStore({});` +- **派生值 (Memos)**: 使用 `createMemo` 创建的派生值，使用 camelCase。 + - 示例: `const fullName = createMemo(() => `${firstName()} ${lastName()}`);` + +## 4. 函数和变量命名 + +- **函数**: 使用 camelCase。函数名应该清晰地表明其执行的动作。 + - 示例: `handleClick`, `fetchData`, `formatDate` +- **事件处理函数**: 通常以 `handle` 开头，后跟事件名称。 + - 示例: `onClick={handleClick}`, `onChange={handleChange}` +- **布尔变量**: 通常以 `is`, `has`, `can` 等开头。 + - 示例: `const isActive = true;`, `let hasError = false;` +- **常量**: 使用 SCREAMING_SNAKE_CASE（全大写下划线命名法）。 + - 示例: `const MAX_ITEMS = 10;`, `const API_URL = '/api';` +- **循环变量**: 简短且具描述性。 + - 示例: `item`, `idx`, `user` + +## 5. 属性 (Props) 命名 + +- **属性名称**: 使用 camelCase。 + - 示例: `` +- **布尔属性**: 避免使用 `isLoggedIn={true}` 这样的冗余写法，直接使用 `isLoggedIn`。 + - 示例: `