后端开发规范Python和Node.js本文档为后端开发团队的核心约束指南。 所有生成的代码、注释、数据库设计必须遵循以下规则。注释必须使用简体中文。一、通用规范1.1 类型安全Python 项目必须使用类型注解Type HintsNode.js 项目必须使用 TypeScript禁止使用anyTS或AnyPython所有函数、变量、API 响应必须定义类型1.2 代码风格Python 遵循 PEP 8 规范使用 Black 格式化Node.js 遵循 ESLint 规则typescript-eslint / node/recommended禁止使用eslint-disable或# noqa跳过检查优先使用异步编程async/await1.3 路径规范禁止使用../../这种相对引入路径统一使用/或项目根目录别名进行模块引入Python 示例from src.utils.logger import loggerNode.js 示例import { logger } from /utils/logger;1.4 API 请求规范所有请求必须包含userId必须处理 loading / error不允许假设接口结构1.5 错误处理统一返回{success:false,code:ERROR_CODE,message:错误描述中文,data:null}1.6 成功响应{success:true,code:200,message:操作成功,data:{}}1.7 代码清理必须移除未使用变量未使用函数未使用 import未使用样式二、Python 规范2.1 项目结构src/ ├── api/ # API 路由层 │ ├── routes/ │ │ ├── user.py │ │ └── order.py │ └── __init__.py ├── services/ # 业务逻辑层 │ ├── user_service.py │ └── order_service.py ├── models/ # 数据模型层 │ ├── user.py │ └── order.py ├── repositories/ # 数据访问层 │ ├── user_repo.py │ └── order_repo.py ├── utils/ # 工具函数目录 │ ├── logger.py # 日志封装 │ ├── response.py # 统一响应封装 │ └── validate.py # 验证工具 ├── config/ # 配置目录 │ ├── database.py # 数据库配置 │ └── settings.py # 应用配置 ├── middleware/ # 中间件 │ ├── auth.py # 鉴权中间件 │ └── error_handler.py # 错误处理中间件 ├── types/ # 类型定义目录 │ ├── api.py # API 相关类型 │ └── models.py # 数据模型类型 ├── constants/ # 常量定义 ├── exceptions/ # 自定义异常 └── main.py # 应用入口2.2 函数注释所有函数必须添加文档字符串包含功能说明参数说明返回值异常说明示例fromtypingimportOptionalfromdatetimeimportdatetimedefformat_date(date:datetime|int,fmt:str%Y-%m-%d %H:%M:%S)-str: 格式化日期时间 Args: date: 日期对象或时间戳 fmt: 格式模板默认为 %Y-%m-%d %H:%M:%S Returns: 格式化后的日期字符串 Raises: ValueError: 当 date 参数无效时抛出错误 # 实现代码pass2.3 异步规范所有 IO 操作必须使用异步数据库查询、HTTP 请求、文件读写使用async def定义异步函数使用await调用异步操作示例fromsqlalchemy.ext.asyncioimportAsyncSessionasyncdefget_user_by_id(db:AsyncSession,user_id:int)-Optional[User]: 根据用户ID获取用户信息 Args: db: 数据库会话 user_id: 用户ID Returns: 用户对象不存在时返回 None resultawaitdb.execute(select(User).where(User.iduser_id))returnresult.scalar_one_or_none()三、Node.js 规范3.1 项目结构src/ ├── api/ # API 路由层 │ ├── routes/ │ │ ├── user.ts │ │ └── order.ts │ └── index.ts ├── services/ # 业务逻辑层 │ ├── userService.ts │ └── orderService.ts ├── models/ # 数据模型层 │ ├── User.ts │ └── Order.ts ├── repositories/ # 数据访问层 │ ├── userRepo.ts │ └── orderRepo.ts ├── utils/ # 工具函数目录 │ ├── logger.ts # 日志封装 │ ├── response.ts # 统一响应封装 │ └── validate.ts # 验证工具 ├── config/ # 配置目录 │ ├── database.ts # 数据库配置 │ └── settings.ts # 应用配置 ├── middleware/ # 中间件 │ ├── auth.ts # 鉴权中间件 │ └── errorHandler.ts # 错误处理中间件 ├── types/ # 类型定义目录 │ ├── api.d.ts # API 相关类型 │ └── models.d.ts # 数据模型类型 ├── constants/ # 常量定义 ├── exceptions/ # 自定义异常 └── app.ts # 应用入口3.2 函数注释所有函数必须添加 JSDoc 注释包含功能说明参数说明返回值异常说明示例/** * 格式化日期时间 * param date - 日期对象或时间戳 * param format - 格式模板如 YYYY-MM-DD HH:mm:ss * returns 格式化后的日期字符串 * throws 当 date 参数无效时抛出错误 */exportconstformatDate(date:Date|number,format:string):string{// 实现代码};3.3 异步规范所有 IO 操作必须使用异步使用async/await语法禁止回调函数Callback Hell示例import{Pool}frompg;/** * 根据用户ID获取用户信息 * param pool - 数据库连接池 * param userId - 用户ID * returns 用户对象不存在时返回 null */exportconstgetUserByIdasync(pool:Pool,userId:number):PromiseUser|null{constresultawaitpool.query(SELECT * FROM users WHERE id $1,[userId]);returnresult.rows[0]||null;};四、数据库规范4.1 通用规范必须使用参数化查询必须有中文注释禁止拼接 SQL表名使用小写单词间用下划线分隔字段名使用小写单词间用下划线分隔4.2 MySQL 规范连接示例importaiomysqlfromcontextlibimportasynccontextmanagerasynccontextmanagerasyncdefget_db_connection(): 获取 MySQL 数据库连接 connawaitaiomysql.connect(hostlocalhost,port3306,useruser,passwordpassword,dbdatabase,charsetutf8mb4)try:yieldconnfinally:conn.close()查询示例asyncdefget_user_by_id(conn,user_id:int)-Optional[dict]: 根据用户ID查询用户信息 Args: conn: 数据库连接 user_id: 用户ID Returns: 用户字典不存在时返回 None asyncwithconn.cursor(aiomysql.DictCursor)ascur:awaitcur.execute(SELECT id, username, email FROM users WHERE id %s,(user_id,))returnawaitcur.fetchone()4.3 PostgreSQL 规范连接示例importasyncpgfromcontextlibimportasynccontextmanagerasynccontextmanagerasyncdefget_db_connection(): 获取 PostgreSQL 数据库连接 connawaitasyncpg.connect(hostlocalhost,port5432,useruser,passwordpassword,databasedatabase)try:yieldconnfinally:awaitconn.close()查询示例asyncdefget_user_by_id(conn,user_id:int)-Optional[asyncpg.Record]: 根据用户ID查询用户信息 Args: conn: 数据库连接 user_id: 用户ID Returns: 用户记录不存在时返回 None returnawaitconn.fetchrow(SELECT id, username, email FROM users WHERE id $1,user_id)4.4 SQLite 规范连接示例importaiosqlitefromcontextlibimportasynccontextmanagerasynccontextmanagerasyncdefget_db_connection(): 获取 SQLite 数据库连接 connawaitaiosqlite.connect(database.db)try:yieldconnfinally:awaitconn.close()查询示例asyncdefget_user_by_id(conn,user_id:int)-Optional[tuple]: 根据用户ID查询用户信息 Args: conn: 数据库连接 user_id: 用户ID Returns: 用户元组不存在时返回 None asyncwithconn.execute(SELECT id, username, email FROM users WHERE id ?,(user_id,))ascursor:returnawaitcursor.fetchone()五、依赖管理5.1 包管理器Python 项目统一使用 pip 或 poetry 进行依赖管理Node.js 项目统一使用 pnpm 进行依赖安装禁止使用 npm 或 yarnNode.js必须包含requirements.txtPython或package.jsonNode.jsPython 示例pipinstall-rrequirements.txtNode.js 示例pnpminstallpackage-name六、接口封装规范6.1 API 路由注释所有 API 路由函数必须添加注释包含接口说明请求参数响应数据异常说明Python 示例FastAPIfromfastapiimportAPIRouter,Depends,HTTPExceptionfromsqlalchemy.ext.asyncioimportAsyncSession routerAPIRouter(prefix/api/users,tags[用户管理])router.get(/{user_id})asyncdefget_user(user_id:int,db:AsyncSessionDepends(get_db),current_user:UserDepends(get_current_user))-ResponseModel[UserInfo]: 获取用户信息 Args: user_id: 用户ID db: 数据库会话 current_user: 当前登录用户 Returns: 用户信息 Raises: HTTPException: 用户不存在时返回 404 userawaituser_service.get_user_by_id(db,user_id)ifnotuser:raiseHTTPException(status_code404,detail用户不存在)returnsuccess_response(datauser)Node.js 示例Expressimport{Router,Request,Response}fromexpress;constrouterRouter();/** * 获取用户信息 * route GET /api/users/:userId * param req.params.userId - 用户ID * param req.user - 当前登录用户 * returns 用户信息 * throws 404 - 用户不存在 */router.get(/:userId,authMiddleware,async(req:Request,res:Response){const{userId}req.params;constuserawaituserService.getUserById(userId);if(!user){returnres.status(404).json({success:false,code:USER_NOT_FOUND,message:用户不存在,data:null});}returnres.json({success:true,code:200,message:操作成功,data:user});});七、安全规范敏感信息处理禁止在代码中硬编码 API Key、数据库密码、JWT Secret 等必须使用环境变量。SQL 注入防护所有数据库查询语句必须使用参数化查询避免直接拼接用户输入。CSRF 防护所有 POST 请求必须包含 CSRF 令牌并在服务器端验证。XSS 防护所有用户输入必须进行 HTML 转义防止 XSS 攻击。密码安全密码必须使用 bcrypt 或 argon2 进行哈希存储禁止明文存储。JWT 安全使用强密钥签名设置合理的过期时间刷新令牌机制八、AI 行为约束核心AI 必须遵守不允许编造接口不允许假设数据库结构不允许跳过鉴权不允许省略错误处理不允许生成未使用代码不允许修改无关文件不明确需求必须询问九、开发工作流必须执行9.1 新功能开发流程分析需求确认接口如不明确必须询问定义类型Python Type Hints / TypeScript设计数据库表结构编写数据访问层编写业务逻辑层编写 API 路由层添加错误处理编写单元测试自检是否符合 AGENTS.md9.2 修改代码流程阅读原代码理解业务逻辑给出修改方案再进行修改禁止直接修改代码而不分析9.3 Debug 流程分析报错定位问题找到根因提供修复方案十、输出规范强制必须输出完整代码必须包含 import必须使用代码块禁止伪代码必须有中文注释修改代码必须说明变更点十一、自检机制必须执行输出前必须检查是否使用类型注解Python或 TypeScript 且无 any是否包含 userIdAPI 请求是否有错误处理是否符合目录结构是否有未使用代码是否符合代码风格规范是否有中文注释是否使用项目根目录路径而非../../相对路径author 是否为 gouxinjie是否使用参数化查询数据库操作是否使用异步编程IO 操作不符合必须自动修正十二、性能规范数据库查询必须添加索引避免 N1 查询问题使用连接池管理数据库连接大数据量查询使用分页使用缓存Redis减少数据库压力API 响应时间控制在 200ms 以内十三、日志规范错误必须记录日志API 请求失败必须打印错误信息日志必须包含请求ID、用户ID、时间戳禁止输出敏感信息token、密码、数据库连接字符串开发环境允许 print/console生产环境必须使用日志框架Python 日志示例importloggingimportuuidfromcontextvarsimportContextVar request_id:ContextVar[str]ContextVar(request_id,default)loggerlogging.getLogger(__name__)deflog_request(user_id:int,action:str,status:str): 记录请求日志 Args: user_id: 用户ID action: 操作描述 status: 操作状态 logger.info(f[{request_id.get()}] 用户{user_id}{action}- 状态:{status},extra{request_id:request_id.get(),user_id:user_id,action:action,status:status})Node.js 日志示例import{v4asuuidv4}fromuuid;import{AsyncLocalStorage}fromasync_hooks;constasyncLocalStoragenewAsyncLocalStoragestring();exportconstlogRequest(userId:number,action:string,status:string):void{constrequestIdasyncLocalStorage.getStore()||unknown;console.log([${requestId}] 用户${userId}${action}- 状态:${status});};十四、测试规范所有业务逻辑必须编写单元测试API 路由必须编写集成测试测试覆盖率不低于 80%使用 pytestPython或 JestNode.jsPython 测试示例importpytestfromunittest.mockimportAsyncMock,MagicMockpytest.mark.asyncioasyncdeftest_get_user_by_id(): 测试根据用户ID获取用户信息 # 准备mock_dbAsyncMock()mock_userMagicMock(id1,usernametest,emailtestexample.com)mock_db.execute.return_value.scalar_one_or_none.return_valuemock_user# 执行resultawaituser_service.get_user_by_id(mock_db,1)# 验证assertresult.id1assertresult.usernametestNode.js 测试示例import{describe,it,expect,jest}fromjest/globals;describe(UserService,(){it(should return user by id,async(){// 准备constmockPool{query:jest.fn().mockResolvedValue({rows:[{id:1,username:test}]})};// 执行constresultawaituserService.getUserById(mockPoolasany,1);// 验证expect(result).toEqual({id:1,username:test});});});十五、MCP / 工具调用规范优先使用工具获取数据不允许伪造数据工具失败必须兜底不确定必须询问用户十六、终极原则优先保证代码质量其次是正确性最后才是开发速度十七、附则所有代码必须自动校验本规范特殊情况必须说明原因违反规范必须拒绝生成代码主要变更说明变更项说明语言支持新增 Python 和 Node.js 双后端语言规范数据库支持新增 MySQL、PostgreSQL、SQLite 三种数据库的异步连接和查询示例项目结构按后端分层架构API / Service / Repository / Model重新设计异步规范强制所有 IO 操作使用 async/await类型安全Python 强制 Type HintsNode.js 强制 TypeScript日志规范新增请求追踪request_id和上下文变量规范测试规范新增 pytest 和 Jest 测试示例author统一为gouxinjie路径规范禁止../../使用项目根目录别名包管理Python 使用 pip/poetryNode.js 使用 pnpm自检机制新增数据库参数化查询和异步编程检查项 感谢阅读想了解更多 我的博客网站 | 记录思考分享干货 我的个人主页 | 关于我、开源项目