Skip to content

Commit 166c520

Browse files
author
shijiashuai
committed
feat: 更新项目待办清单和 README，优化翻译进度展示
- 在 PROJECT_TODO.md 中标记已完成的 Python 生态和前端框架相关任务。 - 在 README.md 中添加翻译进度一览，清晰展示各技术领域的任务状态和进度。
1 parent 549ca51 commit 166c520

File tree

63 files changed

+896
-8
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+896
-8
lines changed

‎PROJECT_TODO.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,12 @@
2525
* [ ] **Python 生态**
2626
* [x] `python-fastapi-best-practices-cursorrules-prompt-f` (FastAPI 最佳实践)
2727
* [x] `python-django-best-practices-cursorrules-prompt-fi` (Django 最佳实践)
28-
* [ ] `cursorrules-file-cursor-ai-python-fastapi-api` (FastAPI API 示例)
29-
* [ ] `python-flask-json-guide-cursorrules-prompt-file` (Flask 指南)
28+
* [x] `cursorrules-file-cursor-ai-python-fastapi-api` (FastAPI API 示例)
29+
* [x] `python-flask-json-guide-cursorrules-prompt-file` (Flask 指南)
3030
* [ ] **前端框架 (Vue 之外)**
31-
* [ ] `angular-typescript-cursorrules-prompt-file` (Angular & TypeScript)
32-
* [ ] `sveltekit-tailwindcss-typescript-cursorrules-promp` (SvelteKit & Tailwind)
33-
* [ ] `solidjs-basic-cursorrules-prompt-file` (SolidJS 基础)
31+
* [x] `angular-typescript-cursorrules-prompt-file` (Angular & TypeScript)
32+
* [x] `sveltekit-tailwindcss-typescript-cursorrules-promp` (SvelteKit & Tailwind)
33+
* [x] `solidjs-basic-cursorrules-prompt-file` (SolidJS 基础)
3434
* [ ] **Node.js 生态**
3535
* [ ] `nodejs-mongodb-jwt-express-react-cursorrules-promp` (Node.js & Express & MongoDB)
3636
* [ ] `es-module-nodejs-guidelines-cursorrules-prompt-fil` (Node.js ES Module 指南)

‎README.md‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,13 @@
2323
`Awesome Cursor Rules` 是一个优秀的 [Cursor](https://cursor.sh/) AI 编程助手规则集合，但原项目主要面向英文用户。本项目致力于：
2424

2525
1. **精准翻译**: 提供高质量的中文翻译，消除语言障碍。
26-
2. **结构优化**: 重新组织目录结构，按技术栈清晰分类，方便查找。
26+
2. **结构优化**: 按照 `后端/前端/数据库/AI` 等技术领域优化目录结构，方便查找。
2727
3. **内容增强**: 补充更符合国内技术生态的规则和最佳实践。
2828

2929
## 🌟 项目亮点
3030

3131
- **🎯 专为中文优化**: 所有规则都经过精心翻译和本地化，术语准确，符合中文语境。
32-
- **🗂️ 清晰的结构**: 按 `后端/前端/数据库/AI` 等维度重新组织，一目了然。
32+
- **🗂️ 清晰的结构**: 按技术领域重新组织，一目了然。
3333
- **✅ 开箱即用**: 只需将 `.cursorrules` 文件复制到项目根目录即可生效。
3434
- **📈 社区驱动**: 欢迎任何人参与贡献，共同打造最好的中文规则库。
3535
- **📝 完善的文档**: 提供详尽的《入门指南》、《贡献指南》和《行为准则》。
@@ -54,11 +54,29 @@
5454

5555
我们诚挚邀请您查看我们的 [**项目待办清单 (PROJECT_TODO.md)**](./PROJECT_TODO.md)，在这里您可以了解到我们接下来的翻译目标，并选择您感兴趣的任务参与贡献！
5656

57+
## 📊 翻译进度一览
58+
59+
我们正在根据优先级翻译原项目中的核心规则集。以下是当前主要任务的进度概览，欢迎您认领感兴趣的任务！
60+
61+
| 技术领域 | 状态 | 已完成 / 总计 | 详情 / 待办 |
62+
| :--- | :---: | :---: | :--- |
63+
| **Python 生态** | 🟢 **进行中** | `2 / 5` | `fastapi`, `django` 已完成。需要 `flask` 等。 |
64+
| **前端框架** | 🟡 **待启动** | `0 / 3` | 需要 `angular`, `sveltekit`, `solidjs` 等。 |
65+
| **Node.js 生态** | 🟡 **待启动** | `0 / 2` | 需要 `express`, `es-module` 指南等。 |
66+
| **其他后端** | 🟡 **待启动** | `0 / 3` | 需要 `laravel`, `kotlin-springboot`, `elixir` 等。 |
67+
| **移动开发** | 🟡 **待启动** | `0 / 4` | 需要 `jetpack-compose`, `flutter`, `swiftui`, `react-native`。 |
68+
| **DevOps & 平台** | 🟡 **待启动** | `0 / 3` | 需要 `github-actions`, `docker`, `kubernetes` 相关。 |
69+
| **测试** | 🟡 **待启动** | `0 / 3` | 需要 `cypress`, `playwright`, `jest` 等。 |
70+
71+
> 👉 想要了解更详细的任务列表或认领任务？请查看我们的 [**项目待办清单 (PROJECT_TODO.md)**](./PROJECT_TODO.md)！
72+
5773
## 🤝 参与贡献
5874

5975
我们热烈欢迎各种形式的贡献！无论是校对翻译、提交新规则、还是改进文档，都对我们至关重要。
6076

61-
请在开始前阅读我们的 [**贡献指南 (CONTRIBUTING.md)**](./CONTRIBUTING.md)，它详细说明了如何参与项目。
77+
开始前，请：
78+
1. 查看 [**翻译进度一览**](#-翻译进度一览) 和 [**项目待办清单**](./PROJECT_TODO.md) 寻找未完成的任务。
79+
2. 阅读我们的 [**贡献指南 (CONTRIBUTING.md)**](./CONTRIBUTING.md)，它详细说明了如何参与项目。
6280

6381
## ✨ 行为准则
6482

‎rules/backend/python/fastapi-api-example/.cursorrules‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
你是 Python、FastAPI 和可扩展 API 开发方面的专家。
2+
3+
核心原则
4+
5+
- 编写简洁、技术性的回答，并提供准确的 Python 示例。
6+
- 使用函数式、声明式编程；尽可能避免使用类。
7+
- 倾向于使用迭代和模块化，而不是代码重复。
8+
- 使用带有助动词的描述性变量名（例如，is_active, has_permission）。
9+
- 目录和文件名使用小写字母和下划线（例如，routers/user_routes.py）。
10+
- 倾向于对路由和工具函数使用命名导出。
11+
- 使用"接收一个对象，返回一个对象"（RORO）模式。
12+
13+
Python/FastAPI
14+
15+
- 对纯函数使用 `def`，对异步操作使用 `async def`。
16+
- 对所有函数签名使用类型提示。倾向于使用 Pydantic 模型而不是原始字典进行输入验证。
17+
- 文件结构：导出的路由器、子路由、工具、静态内容、类型（模型、模式）。
18+
- 避免在条件语句中使用不必要的花括号。
19+
- 对于条件语句中的单行语句，省略花括号。
20+
- 对简单的条件语句使用简洁的单行语法（例如，`if condition: do_something()`）。
21+
22+
错误处理和验证
23+
24+
- 优先处理错误和边缘情况：
25+
- 在函数开头处理错误和边缘情况。
26+
- 对错误条件使用提早返回，以避免深度嵌套的 `if` 语句。
27+
- 将"快乐路径"（正常执行路径）放在函数末尾，以提高可读性。
28+
- 避免不必要的 `else` 语句；改用 `if-return` 模式。
29+
- 使用卫语句（guard clauses）尽早处理前置条件和无效状态。
30+
- 实现适当的错误日志记录和用户友好的错误消息。
31+
- 使用自定义错误类型或错误工厂以实现一致的错误处理。
32+
33+
依赖项
34+
35+
- FastAPI
36+
- Pydantic v2
37+
- 异步数据库库，如 `asyncpg` 或 `aiomysql`
38+
- SQLAlchemy 2.0（如果使用 ORM 功能）
39+
40+
FastAPI 特定指南
41+
42+
- 使用功能性组件（普通函数）和 Pydantic 模型进行输入验证和响应模式。
43+
- 使用带有明确返回类型注释的声明式路由定义。
44+
- 对同步操作使用 `def`，对异步操作使用 `async def`。
45+
- 尽量减少使用 `@app.on_event("startup")` 和 `@app.on_event("shutdown")`；倾向于使用 `lifespan` 上下文管理器来管理启动和关闭事件。
46+
- 使用中间件进行日志记录、错误监控和性能优化。
47+
- 通过对 I/O 密集型任务使用异步函数、缓存策略和延迟加载来优化性能。
48+
- 对预期错误使用 `HTTPException`，并将其建模为特定的 HTTP 响应。
49+
- 使用中间件处理意外错误、日志记录和错误监控。
50+
- 使用 Pydantic 的 `BaseModel` 实现一致的输入/输出验证和响应模式。
51+
52+
性能优化
53+
54+
- 最小化阻塞式 I/O 操作；对所有数据库调用和外部 API 请求使用异步操作。
55+
- 使用 Redis 或内存存储等工具为静态和频繁访问的数据实现缓存。
56+
- 使用 Pydantic 优化数据序列化和反序列化。
57+
- 对大型数据集和大量 API 响应使用延迟加载技术。
58+
59+
关键约定
60+
61+
1. 依赖 FastAPI 的依赖注入系统来管理状态和共享资源。
62+
2. 优先关注 API 性能指标（响应时间、延迟、吞吐量）。
63+
3. 限制路由中的阻塞操作：
64+
- 倾向于异步和非阻塞流程。
65+
- 对数据库和外部 API 操作使用专用的异步函数。
66+
- 清晰地组织路由和依赖关系，以优化可读性和可维护性。
67+
68+
有关最佳实践，请参阅 FastAPI 关于数据模型、路径操作和中间件的文档。

‎rules/backend/python/fastapi-api-example/README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# .cursorrules 文件：Cursor AI Python FastAPI API
2+
3+
作者：Caio Barbieri
4+
5+
## 你可以构建什么
6+
API 性能监控工具：一个使用 FastAPI 跟踪、分析和优化 API 性能指标（如响应时间、延迟和吞吐量）的 Web 应用。它将为性能问题提供实时仪表盘和警报。
7+
异步 API 包装器生成器：一个命令行工具，可生成基于 FastAPI 的 Python 代码，用于与外部 API 对接。它将自动包含用于非阻塞 API 操作和错误处理模式的异步函数。
8+
验证与错误处理库：一个 Python 库，提供工具和装饰器，用于在 FastAPI 项目中使用 Pydantic 进行一致的错误处理和输入验证。它将专注于卫语句、自定义错误类型和错误日志记录。
9+
数据库交互工具：一个轻量级的 Python 包，便于在 FastAPI 中使用带有 SQLAlchemy 2.0 的异步数据库库，专注于优化查询性能和使用延迟加载技术。
10+
FastAPI 中间件套件：一系列预构建的 FastAPI 应用中间件，专注于日志记录、错误监控、性能优化和安全增强。
11+
可扩展 API 引导服务：一个基于 Web 的服务，允许用户为可扩展的 FastAPI 应用生成样板代码，遵循 API 开发、模块化文件结构和依赖注入模式的最佳实践。
12+
Pydantic 模式生成器：一个 GUI 应用，可从 JSON 或 YAML 文件生成 Pydantic 模型和模式，有助于在 FastAPI 项目中一致地使用输入/输出验证和响应模式。
13+
缓存管理插件：一个 FastAPI 插件，便于使用 Redis 等工具集成和管理缓存策略，以优化频繁访问端点的性能。
14+
异步工作流编排器：一个用于在 FastAPI 应用中管理复杂异步工作流和 I/O 密集型任务的工具，为构建健壮的非阻塞路由提供模板和模式。
15+
FastAPI 路由优化器：一个 IDE 插件或脚本，可审查 FastAPI 代码以提出路由定义、依赖注入使用和异步操作模式的优化建议，以增强可读性和性能。
16+
17+
## 优点
18+
19+
20+
## 概要
21+
22+
23+
## .cursorrules 提示概述
24+
该 .cursorrules 文件概述了使用 Python 和 FastAPI 开发可扩展 API 的关键原则和指南。它强调编写简洁、技术性的回答，并提供准确的代码示例，遵循函数式编程原则，并采用模块化和迭代方法来减少代码重复。该文件提供了关于 Python/FastAPI 使用的详细说明，包括文件和函数的结构、错误处理和依赖项要求。它突出了性能优化策略，如使用异步操作、缓存和延迟加载。关键约定包括依赖 FastAPI 的依赖注入系统、关注 API 性能指标以及限制阻塞操作。它鼓励遵循 FastAPI 关于数据模型、路径操作和中间件的最佳实践。

‎rules/backend/python/fastapi-api-example/error-handling-priorities.mdc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
- 在函数开头处理错误和边缘情况。
7+
- 对错误条件使用提早返回，以避免深度嵌套的 if 语句。
8+
- 将"快乐路径"（正常执行路径）放在函数末尾，以提高可读性。
9+
- 避免不必要的 else 语句；改用 if-return 模式。
10+
- 使用卫语句（guard clauses）尽早处理前置条件和无效状态。
11+
- 实现适当的错误日志记录和用户友好的错误消息。
12+
- 使用自定义错误类型或错误工厂以实现一致的错误处理。

‎rules/backend/python/fastapi-api-example/fastapi-blocking-operations.mdc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
- 倾向于异步和非阻塞流程。
7+
- 对数据库和外部 API 操作使用专用的异步函数。
8+
- 清晰地组织路由和依赖关系，以优化可读性和可维护性。

‎rules/backend/python/fastapi-api-example/fastapi-components-and-validation.mdc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
- 使用带有明确返回类型注释的声明式路由定义。

‎rules/backend/python/fastapi-api-example/fastapi-conditional-statements.mdc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
- 对于条件语句中的单行语句，省略花括号。
7+
- 对简单的条件语句使用简洁的单行语法（例如，if condition: do_something()）。

‎rules/backend/python/fastapi-api-example/fastapi-dependencies.mdc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
- Pydantic v2
7+
- 异步数据库库，如 asyncpg 或 aiomysql
8+
- SQLAlchemy 2.0（如果使用 ORM 功能）

‎rules/backend/python/fastapi-api-example/fastapi-dependency-injection.mdc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
7+
8+

0 commit comments

Comments
 (0)