一键导入
cn-coder
中文代码生成规范:命名规范、注释规范、多语言代码规则、CRUD模板、代码审查清单
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
菜单
中文代码生成规范:命名规范、注释规范、多语言代码规则、CRUD模板、代码审查清单
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
国内AI平台API统一封装 —— DeepSeek / 通义千问 / 百度文心 / 讯飞星火 一键切换
一键配置国内AI开发环境——DeepSeek/通义千问/豆包/百度文心/讯飞星火API适配,WSL/Windows/Mac三环境自动检测,代理配置,故障排查
国内云服务部署完全指南 —— 阿里云ECS / 腾讯云 / CDN / 备案 / 镜像加速 / CI/CD / 成本估算
中文Prompt模板库——20+即用模板涵盖代码审查、架构设计、Bug修复、重构、测试、文档、API设计,附最佳实践
中文爬虫工具集 —— Python requests/BS4 爬虫模板、反爬虫绕过、Selenium 自动化、数据导出
WSL/Windows双环境自动化管理——轻松在WSL和Windows之间协作,解决Interop/路径/权限/代理/性能问题
| name | cn-coder |
| description | 中文代码生成规范:命名规范、注释规范、多语言代码规则、CRUD模板、代码审查清单 |
| version | 2.0.0 |
| author | awesome-dev-skill-pack |
| license | MIT |
| metadata | {"hermes":{"tags":["coding","china","convention","style","crud","review","best-practice"],"related_skills":["cn-dev-setup","wsl-helper"]}} |
面向中文团队的 AI 编程规范。解决三个核心痛点:
本规范提供了 命名规范 → 注释模板 → 多语言规则 → 提示词模板 → CRUD 模板 → 审查清单 的完整闭环。
| 层级 | 原则 | 说明 |
|---|---|---|
| 项目/模块 | 英文 | 项目名、包名、模块名统一英文 |
| 代码标识符 | 英文 | 变量/函数/类/方法名统一英文 |
| 注释/文档 | 中文 | 所有自然语言描述使用中文 |
| 配置/资源 | 中文 | 国际化 Key、菜单名、权限名可中文 |
| 数据库 | 英文 | 表名、字段名统一英文 |
# 好
user_name, order_status, get_user_info(), OrderHandler
# 不好 —— 语法错误或中式英文
people_name, buy_goods, do_thing(), ThingDoer
选英文时的原则:
order / invoice / sku / workflow)getUser 不是 userGetbeijing、weixin(微信生态专用)pinyin(拼音本身)、hukou(户口)daKuan 比 makePayment 更可维护严禁拼音场景:
# ❌ 坚决禁止
user_xingming, shoujihao, yonghubiao, btn_dianji
在项目根目录维护 TERMS.md:
# 项目术语对照表
| 中文 | 英文 | 说明 |
|------|------|------|
| 用户 | user | — |
| 订单 | order | — |
| 商品 | product / item | item 特指订单行 |
| 优惠券 | coupon | — |
| 审核 | review | 内容审核用 moderate |
| 提现 | withdraw | — |
| 余额 | balance | — |
| 打款 | payout | 财务付款专用 |
| 分页 | pagination | — |
| 校验 | validate | 后端校验用 verify |
| 转换 | convert / transform | 数据格式转换 |
| 映射 | map / mapping | — |
# ✅ 好
user_name = "张三" # 名词 + 名词
is_active = True # is_ + 形容词
order_list = [] # 名词 + 集合后缀
product_count = 0 # 名词 + 度量词
# ❌ 不好
username = "张三" # 有歧义(username 可以是登录名)
active_flag = True # flag 冗余
arr = [] # 无意义
temp_str = "" # temp/str 无信息量
# ✅ 好
def get_user_info(user_id): ...
def create_order(items, address): ...
def validate_email(email): ...
def is_order_paid(order_id): ...
# 动词习惯:get/create/update/delete + 名词
# 布尔判断:is/has/can/should + 形容词/过去分词
# ❌ 不好
def user_info(): ... # 无动词
def deal_with_order(): ... # deal_with 模糊
def check_email_is_ok(email): ... # is_ok 不规范
def do_thing(): ... # 无意义
# ✅ 好
class OrderService: ...
class UserController: ...
class PaymentProvider: ...
class OrderStatus(Enum): ...
class NotFoundError(Exception): ...
# 名词 + 名词/后缀:Service / Controller / Provider / Handler / Manager / Factory / Builder / Strategy
# ❌ 不好
class OrderThing: ... # 无意义后缀
class DoOrder: ... # 动词开头
class order_utils: ... # 小写下划线
# ✅ 好
MAX_RETRY_COUNT = 3
DEFAULT_PAGE_SIZE = 20
ORDER_STATUS_PENDING = "pending"
API_BASE_URL = "https://api.example.com"
# 全大写 + 下划线
| 项目类型 | 风格 | 示例 |
|---|---|---|
| Python 后端 | 小写下划线 | user_service.py, order_controller.py |
| JavaScript/TS 前端 | 小写连词符 | user-profile.tsx, api-service.ts |
| Go 后端 | 小写下划线 | user_service.go, order_handler.go |
| Rust 后端 | 小写下划线 | user_service.rs, order_model.rs |
| 测试文件 | 与被测文件一致 | user_service_test.py |
1. 注释用中文,代码用英文
2. 注释说明"为什么",不说明"是什么"(代码本身应自说明)
3. 复杂逻辑写注释,简单逻辑不写注释
4. 文档字符串必写,公共 API 必写
5. TODO / FIXME / HACK 用英文标记,中文说明
# 价格必须是正数(业务规则:不允许负定价)
if price <= 0:
raise ValueError("价格不合法")
items = fetch_items() # 从缓存中获取商品列表,若缓存不存在则回源 DB
# ──────────────────────────────────────────────
# 订单超时处理逻辑
# 1. 扫描所有状态为 "待支付" 且超过 30 分钟的订单
# 2. 将其状态变更为 "已取消"
# 3. 释放预占库存
# 4. 发送取消通知给用户
# ──────────────────────────────────────────────
"""
订单模块
提供订单的创建、支付、取消、退款全生命周期管理。
依赖:
- user_service: 用户信息
- payment_service: 支付渠道对接
- inventory_service: 库存锁定与释放
"""
def create_order(
user_id: int,
items: list[OrderItem],
address: Address,
coupon_code: str | None = None
) -> Order:
"""创建订单
校验商品库存、计算金额、应用优惠券、锁定库存。
若校验失败或库存不足,抛出对应的业务异常。
Args:
user_id: 用户 ID
items: 订单商品列表(至少包含一个商品)
address: 收货地址
coupon_code: 优惠券编码(可选)
Returns:
已创建的 Order 对象
Raises:
UserNotFoundError: 用户不存在
InsufficientStockError: 库存不足
CouponInvalidError: 优惠券无效或已过期
Example:
>>> order = create_order(1, [item1], addr, code="NEW2024")
>>> order.status
'pending'
"""
...
/**
* 创建订单
*
* 校验商品库存、计算金额、应用优惠券、锁定库存。
*
* @param {number} userId - 用户 ID
* @param {OrderItem[]} items - 订单商品列表
* @param {Address} address - 收货地址
* @param {string} [couponCode] - 优惠券编码(可选)
* @returns {Promise<Order>} 创建的订单对象
* @throws {UserNotFoundError} 用户不存在
* @throws {InsufficientStockError} 库存不足
*
* @example
* const order = await createOrder(1, [item1], addr, 'NEW2024')
* console.log(order.status) // 'pending'
*/
async function createOrder(userId, items, address, couponCode) { ... }
// CreateOrder 创建订单
//
// 校验商品库存、计算金额、应用优惠券、锁定库存。
// 参数验证失败或库存不足时返回对应的业务错误。
//
// 参数:
// - ctx: 上下文(包含超时控制)
// - req: 创建订单请求体
//
// 返回值:
// - *Order: 已创建的订单对象
// - error: 业务错误(可能为 ErrUserNotFound / ErrInsufficientStock / ErrCouponInvalid)
func CreateOrder(ctx context.Context, req *CreateOrderReq) (*Order, error) { ... }
/// 创建订单
///
/// 校验商品库存、计算金额、应用优惠券、锁定库存。
/// 校验失败或库存不足时返回对应的错误。
///
/// # 参数
/// - `user_id`: 用户 ID
/// - `items`: 订单商品列表
/// - `address`: 收货地址
/// - `coupon_code`: 优惠券编码(可选)
///
/// # 返回值
/// - `Ok(Order)`: 已创建的订单
/// - `Err(AppError)`: 业务错误
///
/// # 示例
/// ```
/// let order = create_order(1, vec![item], addr, Some("NEW2024")).await?;
/// assert_eq!(order.status, OrderStatus::Pending);
/// ```
pub async fn create_order(
user_id: i32,
items: Vec<OrderItem>,
address: Address,
coupon_code: Option<String>,
) -> Result<Order, AppError> { ... }
1. 所有标识符使用英文,注释使用中文
2. 错误消息中英双份(日志用中文,用户端用英文或国际化)
3. 日志消息使用中文,方便排查
4. 配置项注释使用中文
5. 测试用例描述使用中文
# 命名风格:变量/函数 → snake_case,类 → PascalCase,常量 → UPPER_CASE
# 类型注解必须写
# 文件名:小写下划线
# 项目结构:
# my_project/
# ├── app/
# │ ├── __init__.py
# │ ├── main.py # 应用入口
# │ ├── config.py # 配置(中文注释)
# │ ├── models/ # 数据模型
# │ │ ├── __init__.py
# │ │ └── user.py
# │ ├── services/ # 业务逻辑
# │ │ ├── __init__.py
# │ │ └── user_service.py
# │ ├── controllers/ # 接口层
# │ │ ├── __init__.py
# │ │ └── user_controller.py
# │ └── utils/ # 工具函数
# │ └── validators.py
# └── tests/
# ├── conftest.py
# └── test_user_service.py
// 命名风格:变量/函数 → camelCase,类/组件 → PascalCase,常量 → UPPER_CASE
// 文件名:组件用 PascalCase(UserProfile.tsx),工具用小写连词符(api-service.ts)
// TypeScript 类型定义必须写
// 异步函数统一 async/await
// 项目结构(前端):
// src/
// ├── api/ # API 请求层
// │ ├── request.ts # axios/fetch 封装
// │ └── user.ts # 用户相关接口
// ├── components/ # 通用组件
// │ ├── UserTable/
// │ │ ├── index.tsx
// │ │ └── style.module.css
// │ └── Pagination.tsx
// ├── pages/ # 页面组件
// │ └── user/
// │ ├── UserList.tsx
// │ └── UserDetail.tsx
// ├── hooks/ # 自定义 hooks
// │ └── useUser.ts
// ├── types/ # 类型定义
// │ └── user.ts
// ├── utils/ # 工具函数
// │ └── format.ts
// ├── i18n/ # 国际化
// └── App.tsx
// 命名风格:函数 → PascalCase(导出)或 camelCase(私有),变量 → camelCase
// 常量 → PascalCase
// 文件名:小写下划线
// 错误变量以 Err 开头:ErrUserNotFound
// 接口名以 er 结尾:UserService / OrderRepository
// 项目结构:
// my-server/
// ├── cmd/
// │ └── server/
// │ └── main.go # 应用入口
// ├── internal/
// │ ├── config/
// │ │ └── config.go # 配置(中文注释)
// │ ├── model/
// │ │ ├── user.go # 数据模型
// │ │ └── order.go
// │ ├── repo/
// │ │ └── user_repo.go # 数据访问层
// │ ├── service/
// │ │ └── user_service.go # 业务逻辑
// │ ├── handler/
// │ │ └── user_handler.go # HTTP 处理器
// │ └── middleware/
// │ └── auth.go
// ├── pkg/
// │ └── errors/
// │ └── errors.go
// └── go.mod
// 命名风格:变量/函数 → snake_case,类/枚举 → PascalCase
// 常量 → UPPER_CASE
// 文件名:小写下划线
// 错误类型以 Error 结尾,使用 thiserror/anyhow
// 所有公共项必须有文档注释(///)
// 模块结构:
// my-service/
// ├── src/
// │ ├── main.rs # 应用入口
// │ ├── config.rs # 配置(中文注释)
// │ ├── model/
// │ │ ├── mod.rs
// │ │ ├── user.rs # 数据模型
// │ │ └── order.rs
// │ ├── repository/
// │ │ ├── mod.rs
// │ │ └── user_repo.rs # 数据访问层
// │ ├── service/
// │ │ ├── mod.rs
// │ │ └── user_service.rs # 业务逻辑
// │ ├── handler/
// │ │ ├── mod.rs
// │ │ └── user_handler.rs # HTTP 处理器
// │ └── error.rs # 错误定义
// ├── tests/
// └── Cargo.toml
请按照 cn-coder 规范生成以下项目的代码:
项目类型: {Python/JS/Go/Rust}
项目名称: {项目名}
核心功能: {一句话说明}
规范要求:
1. 所有标识符(变量/函数/类/方法/文件名)使用英文
2. 所有注释、文档字符串使用中文
3. 遵循 {语言} 的语言惯例命名风格
4. 项目结构参照 cn-coder 推荐的目录模板
5. 公共函数/方法必须写中文文档字符串
6. 错误消息:日志用中文,用户端用英文
请使用 cn-coder 规范,生成 {实体名} 的 CRUD 代码。
语言: {Python/JS/Go/Rust}
框架: {FastAPI/Express/Gin/Axum}
数据表: {表名}
字段列表:
- {字段名1}: {类型1} — {中文说明1}
- {字段名2}: {类型2} — {中文说明2}
...
请生成:
1. 数据模型定义(含中文注释的字段说明)
2. 创建接口(含输入校验逻辑)
3. 查询接口(支持分页、筛选)
4. 更新接口(部分更新)
5. 删除接口(逻辑删除或物理删除)
6. 单元测试(测试用例用中文描述)
额外要求:
- {可选:权限校验 / 日志记录 / 缓存策略 等}
请按照 cn-coder 规范重构以下代码。
问题描述: {当前代码的问题}
重构目标: {可读性 / 性能 / 可维护性 / 命名优化}
规范要求:
1. 将所有中文拼音命名替换为英文命名
2. 补充中文注释和文档字符串
3. 统一命名风格
4. 抽取重复逻辑为独立函数
以下是原始代码:
```{language}
{代码内容}
### 4.4 提示词模板(代码审查)
请按照 cn-coder 代码审查清单,审查以下代码:
语言: {Python/JS/Go/Rust} 功能: {功能描述}
审查重点:
原始代码:
{代码内容}
---
## 五、CRUD 代码生成模板
### 5.1 通用 API 设计规范
```text
# RESTful API 路径设计
列表查询: GET /api/{资源}?page=1&size=20&status=active
详情查询: GET /api/{资源}/{id}
创建: POST /api/{资源}
更新: PUT /api/{资源}/{id} (全量更新)
部分更新: PATCH /api/{资源}/{id} (推荐)
删除: DELETE /api/{资源}/{id} (逻辑删除)
批量删除: DELETE /api/{资源}?ids=1,2,3
# 统一返回格式
{
"code": 0, # 0=成功,非0=业务错误码
"message": "操作成功", # 中文或英文消息
"data": {}, # 业务数据
"request_id": "..." # 链路追踪 ID
}
# 分页返回格式
{
"code": 0,
"message": "查询成功",
"data": {
"list": [...],
"total": 100,
"page": 1,
"size": 20,
"total_pages": 5
}
}
# 错误返回格式
{
"code": 40001,
"message": "用户不存在",
"detail": "无法找到 ID 为 123 的用户",
"request_id": "..."
}
# user_controller.py —— 用户 CRUD 接口
from fastapi import APIRouter, Depends, HTTPException, Query
from app.services.user_service import UserService
from app.models.user import User
from app.schemas.user import UserCreate, UserUpdate, UserQuery, UserResponse, PaginatedResponse
router = APIRouter(prefix="/api/users", tags=["用户管理"])
@router.get("", response_model=PaginatedResponse[UserResponse])
async def list_users(
query: UserQuery = Depends(),
service: UserService = Depends(),
):
"""获取用户列表(支持分页和筛选)"""
result = await service.list_users(
page=query.page,
size=query.size,
status=query.status,
keyword=query.keyword,
)
return PaginatedResponse(
code=0,
message="查询成功",
data=result,
)
@router.get("/{user_id}", response_model=UserResponse)
async def get_user(user_id: int, service: UserService = Depends()):
"""获取用户详情"""
user = await service.get_user(user_id)
if not user:
raise HTTPException(status_code=404, detail="用户不存在")
return UserResponse(code=0, message="查询成功", data=user)
@router.post("", response_model=UserResponse, status_code=201)
async def create_user(data: UserCreate, service: UserService = Depends()):
"""创建用户"""
user = await service.create_user(data)
return UserResponse(code=0, message="创建成功", data=user)
@router.patch("/{user_id}", response_model=UserResponse)
async def update_user(user_id: int, data: UserUpdate, service: UserService = Depends()):
"""更新用户信息(部分更新)"""
user = await service.update_user(user_id, data)
if not user:
raise HTTPException(status_code=404, detail="用户不存在")
return UserResponse(code=0, message="更新成功", data=user)
@router.delete("/{user_id}")
async def delete_user(user_id: int, service: UserService = Depends()):
"""删除用户(逻辑删除)"""
success = await service.delete_user(user_id)
if not success:
raise HTTPException(status_code=404, detail="用户不存在")
return {"code": 0, "message": "删除成功"}
# user_service.py —— 用户业务逻辑
from app.repositories.user_repo import UserRepository
from app.models.user import User
class UserService:
"""用户业务逻辑层"""
def __init__(self, repo: UserRepository):
self.repo = repo
async def list_users(self, page: int, size: int, status: str | None, keyword: str | None):
"""查询用户列表,支持按状态和关键词筛选"""
offset = (page - 1) * size
users, total = await self.repo.find_all(
offset=offset,
limit=size,
status=status,
keyword=keyword,
)
return {
"list": users,
"total": total,
"page": page,
"size": size,
"total_pages": (total + size - 1) // size,
}
async def get_user(self, user_id: int) -> User | None:
"""根据 ID 获取用户"""
return await self.repo.find_by_id(user_id)
async def create_user(self, data) -> User:
"""创建新用户,含重复检测"""
exists = await self.repo.find_by_email(data.email)
if exists:
raise ValueError("邮箱已被注册")
return await self.repo.create(data)
async def update_user(self, user_id: int, data) -> User | None:
"""更新用户,跳过 None 字段(部分更新)"""
user = await self.repo.find_by_id(user_id)
if not user:
return None
update_data = data.model_dump(exclude_unset=True)
return await self.repo.update(user_id, update_data)
async def delete_user(self, user_id: int) -> bool:
"""逻辑删除用户"""
user = await self.repo.find_by_id(user_id)
if not user:
return False
await self.repo.soft_delete(user_id)
return True
# user_repo.py —— 用户数据访问层
from app.models.user import User
from app.database import db
class UserRepository:
"""用户数据访问层"""
async def find_all(self, offset: int, limit: int, status: str | None, keyword: str | None):
"""查询用户列表,支持筛选和分页"""
query = "SELECT * FROM users WHERE deleted_at IS NULL"
count_query = "SELECT COUNT(*) FROM users WHERE deleted_at IS NULL"
params = []
if status:
query += " AND status = ?"
count_query += " AND status = ?"
params.append(status)
if keyword:
query += " AND (name LIKE ? OR email LIKE ?)"
count_query += " AND (name LIKE ? OR email LIKE ?)"
params.extend([f"%{keyword}%", f"%{keyword}%"])
query += " ORDER BY created_at DESC LIMIT ? OFFSET ?"
params.extend([limit, offset])
rows = await db.fetch_all(query, params)
total = await db.fetch_val(count_query, params[:2]) # 不含 limit/offset 的参数
return [User(**row) for row in rows], total
async def find_by_id(self, user_id: int) -> User | None:
"""根据主键查询用户"""
row = await db.fetch_one(
"SELECT * FROM users WHERE id = ? AND deleted_at IS NULL",
[user_id],
)
return User(**row) if row else None
async def find_by_email(self, email: str) -> User | None:
"""根据邮箱查询用户(用于重复检测)"""
row = await db.fetch_one(
"SELECT * FROM users WHERE email = ? AND deleted_at IS NULL",
[email],
)
return User(**row) if row else None
async def create(self, data) -> User:
"""插入新用户并返回"""
row = await db.fetch_one(
"INSERT INTO users (name, email, phone, status) VALUES (?, ?, ?, ?) RETURNING *",
[data.name, data.email, data.phone, data.status or "active"],
)
return User(**row)
async def update(self, user_id: int, data: dict) -> User | None:
"""更新用户字段(只更新 data 中包含的字段)"""
if not data:
return await self.find_by_id(user_id)
set_clause = ", ".join(f"{k} = ?" for k in data.keys())
values = list(data.values()) + [user_id]
await db.execute(
f"UPDATE users SET {set_clause} WHERE id = ? AND deleted_at IS NULL",
values,
)
return await self.find_by_id(user_id)
async def soft_delete(self, user_id: int):
"""逻辑删除:设置 deleted_at 时间戳"""
await db.execute(
"UPDATE users SET deleted_at = datetime('now') WHERE id = ?",
[user_id],
)
data/info/tmp 是否合理?)is_/has_/can_/should_ 前缀_list/_set 后缀如果项目尚未建立规范,执行以下三步:
touch TERMS.md
# 填入 1.3 节的中英术语对照表模板
在项目根目录创建 CLAUDE.md(Claude Code)或 .cursorrules(Cursor):
# 项目规范
遵循 cn-coder 中文代码生成规范:
## 命名
- 变量/函数/类/文件名使用英文
- 注释/文档使用中文
- 参考 TERMS.md 中的术语对照表
- Python: snake_case | JS/TS: camelCase | Go: PascalCase/snake_case | Rust: snake_case
- 类名使用 PascalCase + 名词后缀
## 注释
- 所有公共函数/方法必须写中文文档字符串
- 说明"为什么",不说明"是什么"
## 项目结构
- controller → service → repository 三层
- 错误统一处理
- 统一返回格式 {code, message, data}
使用 4.4 节的审查提示词模板,或人工对照 6.x 审查清单逐项检查。