当前位置：首页>python>献给Javaer的Python开发规范

献给Javaer的Python开发规范

2026-03-27 01:40:16

本规范以 Python 官方 PEP8、PEP20 等核心规范为基础，参考阿里巴巴 Java 开发手册的结构与约束逻辑，结合 Java 团队的使用习惯制定。规范覆盖大模型智能体开发全场景，按约束力分为【强制】（必须遵守，违反易引发故障 / 可读性灾难）、【推荐】（建议遵守，违反易降低代码质量）、【参考】（按需参考，适配个性化场景）三类；每个规约配套「说明」「正例」「反例」，降低 Java 团队转向 Python 的学习成本。

一、编程规约

1.1 命名规范

规约等级	具体要求	说明	正例	反例
【强制】	包名：全小写字母，无下划线，禁止使用 Python 内置模块名 / 第三方库名	包名需体现功能模块，与 Java 包命名逻辑对齐（层级化），避免命名冲突	`agent.core` 、`utils.text`	`agent_core` （含下划线）、`os`（内置模块名）、`requests`（第三方库名）
【强制】	模块（文件）名：全小写字母，多单词用下划线分隔，禁止驼峰 / 拼音 / 模糊命名	区别于 Java 类文件的大驼峰命名，贴合 Python 官方规范，语义需精准	`model_loader.py` 、`prompt_builder.py`	`ModelLoader.py` （驼峰）、`ceshi.py`（拼音）、`test1.py`（模糊）
【强制】	类名：大驼峰（PascalCase），抽象类前缀`Abstract`，异常类后缀`Exception`，接口类（ABC）前缀`I`	与 Java 类命名完全一致，降低认知成本；Python 无原生接口，ABC 实现的接口类统一前缀标识	`AbstractAgent` 、`ModelCallException`、`IAgentAdapter`	`abstract_agent` （下划线）、`AgentError`（异常类未加 Exception 后缀）
【强制】	函数 / 方法名：全小写，多单词下划线分隔，禁止模糊动词（do/handle）	区别于 Java 的小驼峰，贴合 Python PEP 8；方法名需体现「动作 + 功能」	`load_model_config` 、`parse_user_query`	`LoadModelConfig` （驼峰）、`do_something`（模糊）、`handle_data`（模糊）
【强制】	变量名：全小写，多单词下划线分隔；布尔变量前缀`is_/has_/can_`；常量全大写，下划线分隔	常量无 Python 语法约束，仅通过命名约定区分（类比 Java final 常量）；布尔变量命名贴合 Java 习惯	变量：`user_query`、`max_token`；布尔：`is_initialized`；常量：`MAX_TOKEN_SIZE = 4096`	变量：`UserQuery`（驼峰）；布尔：`initialized`（无前缀）；常量：`maxTokenSize = 4096`（小写 + 驼峰）
【推荐】	函数参数名：语义化，禁止单字母（i/j/df 等通用约定除外）	参数名需明确用途，避免调用者猜含义，类比 Java 方法参数命名	`def call_model(model_name: str, timeout: int)`	`def call_model(m: str, t: int)`

1.2 格式规范

规约等级	具体要求	说明	正例	反例
【强制】	缩进：4 个空格，禁止 Tab；嵌套层级≤4 层	Python 缩进决定代码块，必须统一；嵌套过深易降低可读性，类比 Java 代码块嵌套规范	`python<br>if is_valid:<br> for item in data_list:<br> process_item(item)`	`python<br>if is_valid:<br> for item in data_list:<br> for sub in item:<br> for val in sub:<br> print(val)` （嵌套 5 层）
【强制】	行宽：代码≤79 字符，注释 / 文档字符串≤72 字符；长语句优先在运算符后换行	贴合 Python 官方规范，避免横向滚动，提升可读性	`python<br>response = model.call(<br> prompt=user_query,<br> max_token=MAX_TOKEN_SIZE,<br> timeout=30<br>)`	`python<br>response = model.call(prompt=user_query, max_token=MAX_TOKEN_SIZE, timeout=30)` （超行宽）
【强制】	空格：二元运算符前后各 1 个空格；括号内侧无空格；默认参数等号无空格	与 Java 空格规范对齐，仅默认参数等号特殊（贴合 Python PEP 8）	`python<br>x = 1 + 2<br>func(1, 2)<br>def call_model(timeout=30):`	`python<br>x=1+2<br>func( 1, 2 )<br>def call_model(timeout = 30):`
【推荐】	空行：模块导入后空 1 行；类内方法间空 1 行；函数内逻辑块间空 1 行；文件末尾保留 1 个空行	空行用于分隔逻辑单元，类比 Java 代码格式化习惯，禁止连续空多行	`python<br>import os<br>import sys<br><br>class AgentCore:<br> def __init__(self):<br> pass<br><br> def init(self):<br> pass`	`python<br>import os<br>import sys<br>class AgentCore:<br> def __init__(self):<br> pass<br> def init(self):<br> pass` （无空行分隔）

1.3 导入规范

规约等级	具体要求	说明	正例	反例
【强制】	导入顺序：标准库 → 第三方库 → 自定义库，同类按字母排序，不同类间空 1 行	与 Java 导入顺序（JDK 类→第三方 jar→自研类）对齐，提升可读性	`python<br>import os<br>import sys<br><br>import requests<br>import torch<br><br>from agent.core import AgentCore`	`python<br>from agent.core import AgentCore<br>import os<br>import requests` （顺序混乱）
【强制】	禁止`from xxx import *`通配符导入	避免命名冲突，除非是纯常量模块（需注释说明）	`python<br>from utils.text import parse_query`	`python<br>from utils.text import *`
【推荐】	导入路径：同一包内用相对导入，跨包用绝对导入；相对层级≤2 层	避免复杂相对路径导致的维护成本，类比 Java 包导入逻辑	`python<br># 同一包内<br>from .model_client import ModelClient<br># 跨包<br>from agent.data import VectorStore`	`python<br>from ....core import AgentCore` （相对层级 3 层）

1.4 函数 / 方法规范

规约等级	具体要求	说明	正例	反例
【强制】	单一职责：函数行数≤50 行，仅做一件事；参数个数≤6 个，过多用 dataclass 封装	类比 Java 方法规范，避免大函数；dataclass 替代 Java 实体类，简化多参数传递	`python<br>from dataclasses import dataclass<br><br>@dataclass<br>class ModelParams:<br> name: str<br> timeout: int<br> max_token: int<br><br>def call_model(params: ModelParams):<br> # 仅执行模型调用逻辑（≤50行）<br> pass`	`python<br># 函数含参数校验+模型调用+结果存储（多职责，行数80）<br>def call_model(name, timeout, max_token, url, headers, proxy, retry):<br> # 复杂逻辑<br> pass`
【强制】	默认参数禁止使用列表 / 字典等可变对象	Python 默认参数在函数定义时初始化，可变对象会导致多次调用共享状态	`python<br>def build_prompt(template, variables=None):<br> if variables is None:<br> variables = {}<br> return template.format(**variables)`	`python<br>def build_prompt(template, variables={}):<br> return template.format(**variables)`
【推荐】	函数入口必须校验必填参数（非空 / 类型）	类比 Java 的参数校验，避免非法参数导致后续异常	`python<br>def load_model(model_name: str):<br> if not model_name:<br> raise ValueError("model_name不能为空")<br> if not isinstance(model_name, str):<br> raise TypeError("model_name必须为字符串")`	`python<br>def load_model(model_name):<br> # 无参数校验，直接使用<br> pass`
【推荐】	函数返回值类型统一，禁止同一函数返回不同类型	类比 Java 返回值规范，避免调用者处理类型混乱	`python<br># 始终返回列表（空列表替代None）<br>def get_valid_data() -> list:<br> if not data:<br> return []<br> return [item for item in data if item.is_valid()]`	`python<br># 有时返回列表，有时返回None<br>def get_valid_data():<br> if not data:<br> return None<br> return [item for item in data if item.is_valid()]`

1.5 控制语句规范

规约等级	具体要求	说明	正例	反例
【强制】	异常捕获必须指定具体类型，禁止`except:`/`except Exception:`	类比 Java「捕获具体异常」原则，避免吞掉系统级异常（如 KeyboardInterrupt）	`python<br>try:<br> requests.get(url, timeout=10)<br>except requests.exceptions.Timeout:<br> logger.error("请求超时")<br>except requests.exceptions.ConnectionError:<br> logger.error("连接失败")`	`python<br>try:<br> requests.get(url, timeout=10)<br>except:<br> logger.error("请求异常")`
【强制】	禁止空的 if/elif/else/except 块，无逻辑时加`# TODO`注释	避免代码逻辑缺失，便于后续维护	`python<br>if condition:<br> # TODO: 待实现模型降级逻辑<br>else:<br> process_normal()`	`python<br>if condition:<br> pass<br>else:<br> process_normal()`
【推荐】	if-elif 个数≤5 个，过多用字典映射 / 策略模式替代	类比 Java switch-case 优化，避免条件判断嵌套过深	`python<br># 字典映射替代多elif<br>handler_map = {<br> "gpt-4": handle_gpt4,<br> "claude": handle_claude,<br> "qwen": handle_qwen<br>}<br>handler = handler_map.get(model_name, handle_default)<br>handler(prompt)`	`python<br>if model_name == "gpt-4":<br> handle_gpt4(prompt)<br>elif model_name == "claude":<br> handle_claude(prompt)<br>elif model_name == "qwen":<br> handle_qwen(prompt)<br>elif model_name == "llama":<br> handle_llama(prompt)<br>elif model_name == "ernie":<br> handle_ernie(prompt)<br>else:<br> handle_default(prompt)`
【推荐】	循环中禁止滥用 break/continue（≤1 个 / 循环），禁止死循环（无明确退出条件）	避免逻辑混乱，死循环仅允许服务监听等场景，且需明确退出条件	`python<br># 单break，退出条件清晰<br>for item in data_list:<br> if item.is_invalid():<br> break<br> process_item(item)`	`python<br># 多个break/continue，逻辑混乱<br>for item in data_list:<br> if item.skip:<br> continue<br> if item.is_invalid():<br> break<br> if item.need_retry:<br> continue<br> process_item(item)`

1.6 数据类型规范

规约等级	具体要求	说明	正例	反例
【强制】	字符串拼接：大量字符串用`str.join()`，格式化用 f-string，禁止 % 格式化	f-string（Python3.6+）简洁高效，join () 避免多次字符串拷贝，类比 Java StringBuilder	`python<br># 少量拼接<br>info = f"模型：{model_name}，版本：{version}"<br># 大量拼接<br>parts = [str(i) for i in range(1000)]<br>result = "".join(parts)`	`python<br>info = "模型：%s，版本：%s" % (model_name, version)<br># 大量拼接用+，效率低<br>result = ""<br>for i in range(1000):<br> result += str(i)`
【推荐】	字典取值优先用`get()`方法，避免 KeyError；遍历字典用`items()`	类比 Java Map 的 getOrDefault ()，提升代码健壮性	`python<br>config = {"model_name": "gpt-4"}<br>name = config.get("model_name", "default")<br>for key, value in config.items():<br> print(f"{key}: {value}")`	`python<br>name = config["model_name"] # 无key时抛KeyError<br>for key in config:<br> value = config[key] # 冗余取值`
【推荐】	函数 / 方法添加类型提示（参数 + 返回值）	类比 Java 的类型声明，提升可读性和 IDE 提示效率，降低 Java 团队理解成本	`python<br>from typing import List, Optional<br><br>def parse_queries(queries: List[str]) -> Optional[List[str]]:<br> pass`	`python<br>def parse_queries(queries):<br> pass`

1.7 注释规范

结合 Python 官方 PEP 257（文档字符串规范）、PEP 8 注释要求，对齐 Java 团队 Javadoc 注释习惯，制定以下注释规范，仍按【强制】【推荐】【参考】分级，配套「说明」「正例」「反例」：

规约等级	具体要求	说明	正例	反例
【强制】	所有公共模块 / 类 / 函数 / 方法必须编写文档字符串（Docstring），使用三重引号（"""）包裹	类比 Java 的 Javadoc 注释，Python 官方要求公共 API 必须有 Docstring；Docstring 用于说明「功能、用法、参数 / 返回值」，区别于普通行内注释	`python<br>def load_model_config(model_name: str) -> dict:<br> """<br> 加载指定模型的配置文件<br> <br> Args:<br> model_name (str): 模型名称（如gpt-4、claude）<br> <br> Returns:<br> dict: 模型配置字典（含max_token、temperature等）<br> <br> Raises:<br> FileNotFoundError: 配置文件不存在时抛出<br> """<br> pass`	`python<br># 无Docstring，仅靠变量名猜测功能<br>def load_model_config(model_name):<br> pass`
【强制】	行内注释使用`#`，与代码间保留 1 个空格；仅解释「为什么做」，不解释「做什么」	Python 行内注释语法为`#`（类比 Java 的`//`）；避免冗余注释（如注释 “x=1 # 赋值 x 为 1”），仅注释非直观逻辑	`python<br>time.sleep(1) # 延迟1秒，避免接口QPS限流触发`	`python<br>time.sleep(1)#休眠1秒（无空格）<br>x = 1 + 2 # 计算x的值（冗余注释）`
【强制】	注释语言统一使用中文（团队内部开发），专业术语（如 Prompt Injection）可保留英文	贴合 Java 团队中文注释习惯，避免中英文混杂降低可读性	`python<br># 过滤敏感词，防止Prompt Injection攻击`	`python<br># Filter sensitive words to prevent 提示注入攻击（混杂中英文）<br># Check user query length（纯英文，不符合团队习惯）`
【强制】	禁止注释掉的代码提交到仓库（调试用注释代码需删除）	注释代码会增加维护成本，类比 Java 代码提交规范；调试代码可通过版本历史回溯，无需保留	`python<br># 调试完成后删除以下注释代码<br># temp_config = {"temperature": 0.8}<br># print(temp_config)` （提交前删除上述注释代码）	`python<br># 临时调试代码，暂保留<br>temp_config = {"temperature": 0.8}<br># print(temp_config)`
【推荐】	文档字符串（Docstring）统一使用 Google 风格（简洁易读，适配 Java 团队）	Google 风格比 NumPy 风格更贴近 Java Javadoc 逻辑，便于团队快速适应；核心包含 Args/Returns/Raises/Examples（可选）	python<br>class LLMClient(ABC):<br> """<br> 大模型客户端抽象类，定义模型调用的统一接口<br> <br> 属性：<br> model_name (str): 模型名称<br> max_retry (int): 最大重试次数，默认3次<br> <br> 核心方法：<br> generate: 抽象方法，子类需实现模型响应生成逻辑<br> """<br> @abstractmethod<br> def generate(self, prompt: str) -> str:<br> """<br> 生成模型响应<br> <br> Args:<br> prompt (str): 用户输入的提示词<br> <br> Returns:<br> str: 模型生成的响应文本<br> <br> Raises:<br> ModelCallException: 模型调用失败时抛出<br> <br> Examples:<br> >>> client = GPTClient("gpt-4")<br> >>> client.generate("你好")<br> "你好！有什么我能帮助你的吗？"<br> """<br> pass	`python<br>class LLMClient(ABC):<br> """大模型客户端抽象类"""<br> @abstractmethod<br> def generate(self, prompt):<br> """生成响应"""<br> pass`
【推荐】	多行注释（块注释）用`#`逐行开头，禁止用三重引号（三重引号仅用于 Docstring）	区分「文档字符串（说明功能）」和「普通注释（说明逻辑）」，避免混淆；块注释用于解释复杂逻辑块的设计思路	`python<br># 以下逻辑处理大模型响应脱敏<br># 1. 加载敏感词库（来自config/sensitive_words.txt）<br># 2. 替换响应中的手机号、邮箱等隐私信息<br># 3. 过滤违规敏感词，返回合规响应<br>def filter_response(response: str) -> str:<br> pass`	`python<br>"""<br>以下逻辑处理大模型响应脱敏<br>1. 加载敏感词库<br>2. 替换隐私信息<br>3. 过滤敏感词<br>"""<br>def filter_response(response: str) -> str:<br> pass`
【推荐】	特殊注释（TODO/FIXME）格式统一：`# TODO: 责任人截止时间待办内容`/`# FIXME: 责任人问题描述`	类比 Java 的`// TODO: 张三 2026-03-01 补充降级逻辑`，便于团队协作和任务追踪	`python<br># TODO: 李四 2026-02-28 适配通义千问模型的参数格式<br># FIXME: 王五 2026-02-25 修复模型超时重试次数不生效问题`	`python<br># 待适配通义千问模型（无统一格式）<br># 修复重试次数问题（无责任人/时间）`
【参考】	私有函数 / 方法（下划线开头）可简化 Docstring，仅说明核心逻辑（无需详细参数）	私有成员仅内部使用，注释可简化，重点关注公共 API 的注释完整性	`python<br>def _parse_response_raw(raw_response: str) -> dict:<br> """解析模型原始响应为字典（内部方法）"""<br> pass`	`python<br>def _parse_response_raw(raw_response: str) -> dict:<br> """<br> 解析模型原始响应为字典<br> <br> Args:<br> raw_response (str): 模型原始响应字符串<br> <br> Returns:<br> dict: 解析后的字典<br> """<br> pass`
【参考】	复杂逻辑（如算法、多分支判断）需增加块注释，说明设计思路 / 分支条件	帮助后续维护者理解代码设计意图，类比 Java 复杂逻辑的块注释	`python<br># 模型选择逻辑：<br># - 若用户指定模型，优先使用指定模型<br># - 若未指定，根据查询长度自动选择（短查询用gpt-3.5，长查询用gpt-4）<br># - 若模型不可用，降级到通义千问<br>if user_model:<br> client = get_client(user_model)<br>elif len(prompt) < 100:<br> client = get_client("gpt-3.5")<br>else:<br> client = get_client("gpt-4")<br>if not client.is_available():<br> client = get_client("qwen")`	`python<br># 选择模型<br>if user_model:<br> client = get_client(user_model)<br>elif len(prompt) < 100:<br> client = get_client("gpt-3.5")<br>else:<br> client = get_client("gpt-4")<br>if not client.is_available():<br> client = get_client("qwen")`

二、异常日志规约

2.1 异常处理规范

规约等级	具体要求	说明	正例	反例
【强制】	自定义异常继承`Exception`，禁止继承`BaseException`；异常信息需包含具体原因	类比 Java 自定义异常规范，避免捕获系统级异常；异常信息需可追溯问题	`python<br>class AgentInitException(Exception):<br> """智能体初始化异常"""<br> pass<br><br>raise AgentInitException(f"模型加载失败：{model_name}，错误：{str(e)}")`	`python<br>class AgentInitException(BaseException):<br> pass<br><br>raise AgentInitException("模型加载失败") # 无具体原因`
【强制】	捕获异常后必须处理（日志 / 重试 / 抛上层），禁止`except Exception: pass`	禁止吞异常，类比 Java「不捕获不处理」原则，确保问题可追溯	`python<br>try:<br> load_model()<br>except AgentInitException as e:<br> logger.error(f"模型加载失败：{str(e)}", exc_info=True)<br> raise # 抛上层处理`	`python<br>try:<br> load_model()<br>except Exception:<br> pass # 吞异常，无任何处理`
【推荐】	资源释放优先用`with`语句（上下文管理器），替代 try-finally	Python 特有语法，自动释放资源（文件 / 连接），类比 Java try-with-resources	`python<br>with open("config.json", "r") as f:<br> config = json.load(f)`	`python<br>f = open("config.json", "r")<br>try:<br> config = json.load(f)<br>finally:<br> f.close()`
【参考】	异常链用`raise NewExc() from e`保留原始堆栈	便于追溯异常根源，Python 3.10 + 支持`except*`捕获多异常	`python<br>try:<br> requests.get(url)<br>except requests.exceptions.Timeout as e:<br> raise AgentCallException("接口超时") from e`	`python<br>try:<br> requests.get(url)<br>except requests.exceptions.Timeout:<br> raise AgentCallException("接口超时")`

2.2 日志使用规范

规约等级	具体要求	说明	正例	反例
【强制】	日志级别：DEBUG（调试）、INFO（正常运行）、WARNING（潜在风险）、ERROR（功能异常）、CRITICAL（系统崩溃）；禁止用`print()`替代日志	与 Java 日志级别完全对齐，`print()`无法统一管理，禁止使用	`python<br>import logging<br><br>logger = logging.getLogger(__name__)<br>logger.info("智能体初始化完成，模型：%s", model_name)<br>logger.error("模型调用失败", exc_info=True)`	`python<br>print("智能体初始化完成") # 用print替代日志<br>logger.debug("生产环境输出调试日志") # 生产环境输出DEBUG`
【强制】	日志格式统一：时间 + 级别 + 模块 + 函数 + 信息 + 堆栈（ERROR/CRITICAL）；敏感信息（token / 密码）必须脱敏	便于日志检索和问题排查，类比 Java 日志格式规范	`python<br>logging.basicConfig(<br> format="%(asctime)s - %(levelname)s - %(module)s:%(funcName)s - %(message)s",<br> datefmt="%Y-%m-%d %H:%M:%S"<br>)<br>logger.info("用户登录，用户名：%s", mask_username(username))`	`python<br>logging.basicConfig(format="%(message)s") # 格式缺失<br>logger.info("用户登录，token：%s", token) # 敏感信息未脱敏`
【推荐】	生产环境日志输出到文件（按日期轮转），禁止仅输出到控制台	避免日志丢失，便于长期留存和分析	`python<br>from logging.handlers import TimedRotatingFileHandler<br><br>handler = TimedRotatingFileHandler("agent.log", when="D", backupCount=7)<br>logger.addHandler(handler)`	`python<br># 仅输出到控制台，生产环境无日志文件<br>logging.basicConfig(level=logging.INFO)`

三、单元测试规约

3.1 测试基础规范

规约等级	具体要求	说明	正例	反例
【强制】	测试文件命名：`test_+业务模块名.py`；测试函数命名：`test_+功能名`	贴合 Python pytest/unittest 规范，类比 Java 测试类命名（XxxTest）	`test_model_loader.py` 、`test_load_model_config`	`model_loader_test.py` 、`test1`
【强制】	单元测试需覆盖核心逻辑（分支 / 异常场景），禁止仅测试正常流程	类比 Java 单元测试规范，确保核心功能健壮性	`python<br>def test_load_model_config():<br> # 正常场景<br> config = load_model_config("gpt-4")<br> assert config["max_token"] == 4096<br> # 异常场景<br> with pytest.raises(ValueError):<br> load_model_config("")`	`python<br>def test_load_model_config():<br> config = load_model_config("gpt-4")<br> assert config["max_token"] == 4096`
【推荐】	测试数据与业务代码分离，禁止硬编码测试数据	提升测试用例可维护性，类比 Java 测试的测试数据文件	`python<br># test_data.yaml<br>model_config:<br> gpt-4: {max_token: 4096}<br><br># 测试函数<br>def test_load_model_config():<br> with open("test_data.yaml") as f:<br> test_data = yaml.load(f)<br> config = load_model_config("gpt-4")<br> assert config["max_token"] == test_data["model_config"]["gpt-4"]["max_token"]`	`python<br>def test_load_model_config():<br> # 硬编码测试数据<br> config = load_model_config("gpt-4")<br> assert config["max_token"] == 4096`
【参考】	单元测试独立运行，禁止依赖外部服务（数据库 / 接口），优先 Mock	类比 Java Mock 测试，确保测试用例稳定、快速执行	`python<br>@mock.patch("agent.core.model_client.ModelClient.call")<br>def test_agent_call(mock_call):<br> mock_call.return_value = "测试响应"<br> agent = AgentCore()<br> response = agent.call("测试查询")<br> assert response == "测试响应"`	`python<br>def test_agent_call():<br> # 依赖真实模型接口，不稳定<br> agent = AgentCore()<br> response = agent.call("测试查询")<br> assert response is not None`

四、安全规约

4.1 基础安全规范

规约等级	具体要求	说明	正例	反例
【强制】	敏感信息（API 密钥 /token/ 数据库密码）禁止硬编码，需通过环境变量 / 配置中心读取	避免代码泄露敏感信息，类比 Java 配置中心规范	`python<br>import os<br><br>API_KEY = os.getenv("LLM_API_KEY")<br>if not API_KEY:<br> raise ValueError("未配置LLM_API_KEY环境变量")`	`python<br>API_KEY = "sk-xxxxxx" # 硬编码密钥`
【强制】	用户输入必须校验（类型 / 长度 / 特殊字符），禁止直接传入大模型 / 数据库	防止注入攻击（提示注入 / SQL 注入），保障大模型智能体安全	`python<br>def validate_query(query: str) -> str:<br> if len(query) > 1000:<br> raise ValueError("查询长度超过限制")<br> # 过滤特殊注入字符<br> return query.replace(";", "").replace("'", "")`	`python<br>def call_llm(query: str):<br> # 无输入校验，直接传入<br> return model.generate(query)`
【推荐】	依赖包指定具体版本，禁止`>=`/`<=`模糊版本；定期更新依赖（修复安全漏洞）	避免依赖版本冲突 / 安全漏洞，类比 Java 依赖版本锁定	`python<br># requirements.txt<br>requests==2.31.0<br>langchain==0.1.10`	`python<br># requirements.txt<br>requests>=2.0.0<br>langchain`
【参考】	大模型响应需过滤敏感信息（隐私 / 违规内容），输出前做内容审核	符合合规要求，避免智能体输出违规内容	`python<br>def filter_response(response: str) -> str:<br> sensitive_words = ["敏感词1", "敏感词2"]<br> for word in sensitive_words:<br> response = response.replace(word, "***")<br> return response`	`python<br>def return_response(response: str):<br> # 无内容审核，直接返回<br> return response`

五、MySQL 数据库规约

5.1 数据库操作规范

规约等级	具体要求	说明	正例	反例
【强制】	禁止拼接 SQL 语句，必须使用参数化查询（% s/named 参数）	防止 SQL 注入，类比 Java PreparedStatement 规范	`python<br>import pymysql<br><br>conn = pymysql.connect(host=os.getenv("DB_HOST"), user=os.getenv("DB_USER"))<br>with conn.cursor() as cur:<br> # 参数化查询<br> cur.execute("SELECT * FROM agent_log WHERE user_id = %s", (user_id,))<br> result = cur.fetchall()`	`python<br># 拼接SQL，易注入<br>cur.execute(f"SELECT * FROM agent_log WHERE user_id = {user_id}")`
【强制】	数据库连接使用连接池，禁止频繁创建 / 关闭连接	提升性能，类比 Java 数据库连接池规范	`python<br>from DBUtils.PooledDB import PooledDB<br><br>pool = PooledDB(<br> creator=pymysql,<br> maxconnections=10,<br> host=os.getenv("DB_HOST")<br>)<br>conn = pool.connection()`	`python<br># 每次查询创建连接，性能差<br>def query_data():<br> conn = pymysql.connect(host=os.getenv("DB_HOST"))<br> # 查询逻辑<br> conn.close()`
【推荐】	ORM 框架（SQLAlchemy）使用模型类映射表，禁止直接操作原生 SQL（复杂查询除外）	类比 Java MyBatis/ JPA，提升代码可读性	`python<br>from sqlalchemy import Column, String, Integer<br>from sqlalchemy.ext.declarative import declarative_base<br><br>Base = declarative_base()<br><br>class AgentLog(Base):<br> __tablename__ = "agent_log"<br> id = Column(Integer, primary_key=True)<br> user_id = Column(String(64))<br> query = Column(String(1000))`	`python<br># 所有操作均用原生SQL，可读性差<br>def add_log(user_id, query):<br> cur.execute("INSERT INTO agent_log (user_id, query) VALUES (%s, %s)", (user_id, query))`
【参考】	大结果集查询使用分页（LIMIT/OFFSET），禁止一次性查询全表	避免内存溢出，提升查询性能	`python<br>cur.execute("SELECT * FROM agent_log LIMIT %s OFFSET %s", (page_size, page_num * page_size))`	`python<br>cur.execute("SELECT * FROM agent_log") # 全表查询，数据量大时溢出`

六、工程结构规约

6.1 项目结构规范

规约等级	具体要求	说明	正例（目录结构）	反例
【强制】	项目结构分层：核心业务（agent）、配置（config）、工具（utils）、测试（tests）、文档（docs）	类比 Java Maven 项目结构（src/main/java、src/test/java），便于团队快速定位代码	<br>agent_project/<br>├── agent/ # 核心业务（类比src/main/java）<br>│ ├── core/ # 智能体核心逻辑<br>│ ├── data/ # 数据处理<br>│ ├── api/ # 对外接口<br>│ └── exception/ # 自定义异常<br>├── config/ # 配置文件（类比src/main/resources）<br>├── utils/ # 工具类（类比util包）<br>├── tests/ # 单元测试（类比src/test/java）<br>├── docs/ # 文档<br>├── requirements.txt # 依赖清单（类比pom.xml）<br>└── README.md<br>	`<br>agent_project/<br>├── core.py # 无分层，文件散落<br>├── test.py<br>├── config.yaml<br>└── utils.py<br>`
【强制】	每个 Python 包必须包含`__init__.py`（即使为空）	标识 Python 包，确保导入路径正确，类比 Java 包的 package 声明	`agent/core/__init__.py`	无`__init__.py`，导入时提示「No module named agent.core」
【推荐】	依赖分为生产依赖（requirements.txt）和开发依赖（requirements-dev.txt）	区分运行时和开发时依赖，减少生产环境依赖体积	`<br># requirements.txt（生产）<br>requests==2.31.0<br>langchain==0.1.10<br><br># requirements-dev.txt（开发）<br>pytest==7.4.3<br>flake8==6.1.0<br>`	`<br># 所有依赖混在requirements.txt<br>requests==2.31.0<br>pytest==7.4.3<br>`
【参考】	使用`pyproject.toml`管理项目构建（替代 setup.py），贴合 Python 现代工程规范	适配 PEP 621，类比 Java 的 pom.xml，统一项目构建配置	`toml<br># pyproject.toml<br>[project]<br>name = "agent-core"<br>version = "1.0.0"<br>dependencies = ["requests==2.31.0"]<br>`	仅用 setup.py，无统一构建配置

6.2 版本控制规范

规约等级	具体要求	说明	正例	反例
【强制】	`.gitignore` 必须包含 Python 编译文件（pycache/.pyc）、环境变量文件（.env）、日志文件（.log）	避免提交无关文件，类比 Java 的.gitignore（target/）	`<br># .gitignore<br>__pycache__/<br>.pyc<br>.env<br>.log<br>venv/<br>`	无.gitignore，提交__pycache__/.env 等文件到仓库
【推荐】	Git 分支规范：main（生产）、develop（开发）、feature/xxx（功能）、bugfix/xxx（修复）	类比 Java 团队 GitFlow 规范，避免分支混乱	`feature/model-loader` 、`bugfix/agent-init`	直接在 main 分支开发、分支命名为`test`/`fix1`

6.3 包结构规范

结合 Python 包设计原则（PEP 420）、Java 包分层思想（领域驱动 / 分层架构），针对大模型智能体开发场景制定包结构规范，延续【强制】【推荐】【参考】分级，配套「说明」「正例」「反例」，确保包结构「分层清晰、职责单一、依赖可控」：

规约等级	具体要求	说明	正例	反例
【强制】	核心业务包按「业务领域 / 功能」分层，禁止按「技术类型」拆分（如禁止将所有模型调用、提示构建、记忆管理混放）	类比 Java 的 DDD 领域分层（而非 Controller/Service/DAO 纯技术分层），适配大模型智能体的核心场景；每个包仅承担一类业务职责，避免技术栈耦合	`<br># 按业务领域拆分（大模型智能体场景）<br>agent/<br>├── core/ # 智能体核心逻辑（状态管理、任务调度）<br>├── adapter/ # 模型适配层（GPT/Claude/通义千问适配）<br>├── prompt/ # 提示工程（模板管理、变量渲染）<br>├── memory/ # 智能体记忆（短期/长期记忆存储）<br>└── output/ # 输出处理（响应格式化、敏感信息过滤）<br>`	`<br># 按技术类型拆分（混乱）<br>agent/<br>├── utils/ # 混有提示处理、模型调用、记忆操作的工具函数<br>├── classes/ # 所有类都放这里（核心类、适配类、记忆类）<br>└── functions/ # 所有函数都放这里<br>`
【强制】	包层级深度≤3 层，禁止过深嵌套	避免导入路径复杂（如`from agent.core.adapter.model.gpt import GPTClient`），类比 Java 包层级不超过 4 层的规范；3 层足以覆盖绝大多数大模型智能体场景	`<br># 3层示例（顶级包+业务包+子功能包）<br>agent/adapter/gpt/ # agent（1）→ adapter（2）→ gpt（3）<br>`	`<br># 4层嵌套（过深）<br>agent/core/model/adapter/gpt/ # 导入路径冗长，维护成本高<br>`
【强制】	每个包的`__init__.py`必须包含「包职责说明 Docstring」，禁止空`__init__.py`（无任何注释 / 导出）	`__init__.py` 不仅标识 Python 包，还需说明包的核心职责，便于开发者快速理解；类比 Java 包的 package-info.java 文件	`python<br># agent/adapter/__init__.py<br>"""<br>模型适配层：统一不同大模型的调用接口，屏蔽模型间的参数/响应格式差异<br>支持GPT、Claude、通义千问等主流大模型，新增模型需实现BaseAdapter接口<br>"""<br>from .base import BaseAdapter<br>from .gpt import GPTAdapter<br>from .claude import ClaudeAdapter<br>`	`python<br># agent/adapter/__init__.py<br># 空文件，无任何注释/导出`
【强制】	禁止包之间循环导入，依赖需单向（如 adapter 依赖 core，core 不得依赖 adapter）	循环导入是 Python 常见致命问题，类比 Java 循环依赖的规避原则；核心包（core）作为底层，仅被其他包依赖，不反向依赖	`<br># 单向依赖（正确）<br>adapter/ → core/ （adapter导入core的BaseModel类）<br>prompt/ → core/ （prompt导入core的Config类）<br>`	`<br># 循环导入（错误）<br>core/ 导入 adapter/的GPTAdapter<br>adapter/ 导入 core/的BaseModel<br>`
【推荐】	通用能力抽离为独立顶级包（common/utils），禁止在业务包内重复实现通用逻辑	类比 Java 的 common/util 包，统一通用能力（如日志、加密、配置读取），避免多个业务包重复写「字符串脱敏」「HTTP 请求」等逻辑	`<br># 通用包拆分<br>common/<br>├── log/ # 日志配置（统一日志格式、轮转）<br>├── crypto/ # 加密解密（API密钥脱敏）<br>└── config/ # 配置读取（统一加载YAML/环境变量）<br>`	`<br># 重复实现通用逻辑（错误）<br>agent/adapter/utils.py # 实现HTTP请求<br>agent/prompt/utils.py # 又实现一套HTTP请求<br>`
【推荐】	多环境配置按「环境」拆分到 config 子包，禁止不同环境配置混放	适配开发 / 测试 / 生产多环境部署，类比 Java 的 application-dev.yml/application-prod.yml；配置包需与业务包解耦	`<br>config/<br>├── dev/ # 开发环境配置<br>│ ├── model_config.yaml<br>│ └── db_config.yaml<br>├── test/ # 测试环境配置<br>└── prod/ # 生产环境配置（敏感信息通过环境变量注入）<br>`	`<br># 配置混放（错误）<br>config/<br>├── model_config_dev.yaml<br>├── model_config_test.yaml<br>└── model_config_prod.yaml<br>`
【推荐】	测试包结构与业务包「镜像对齐」，禁止测试文件散乱存放	便于快速定位「业务代码 - 测试代码」对应关系，类比 Java 的 src/test/java 与 src/main/java 镜像结构；测试包层级与业务包完全一致	`<br># 镜像对齐（正确）<br>agent/core/agent_core.py → tests/agent/core/test_agent_core.py<br>agent/adapter/gpt/gpt_adapter.py → tests/agent/adapter/gpt/test_gpt_adapter.py<br>`	`<br># 测试文件散乱（错误）<br>tests/<br>├── test_agent_core.py<br>├── test_gpt_adapter.py<br>└── test_claude_adapter.py<br>`
【参考】	大型项目按「独立模块」拆分顶级包，小型项目合并为单一顶级包	灵活适配项目规模：单智能体小项目用`agent/`单顶级包；多智能体 / 多模块项目拆分顶级包，降低单包复杂度	`<br># 大型项目（多模块）<br>agent_llm/ # LLM智能体核心<br>agent_vector/ # 向量库管理模块<br>agent_api/ # 对外API模块<br>agent_admin/ # 后台管理模块<br><br># 小型项目（单模块）<br>agent/ # 所有逻辑在一个顶级包内<br>`	`<br># 小型项目过度拆分（错误）<br>agent_core/<br>agent_prompt/<br>agent_memory/<br>`
【参考】	包内公共接口导出到`__init__.py`，外部仅通过包名导入（禁止直接导入子模块）	简化导入路径，隐藏内部实现细节，类比 Java 的「包级导出」；外部调用无需关注子模块结构，降低耦合	`python<br># agent/adapter/__init__.py 导出公共接口<br>from .base import BaseAdapter<br>from .gpt import GPTAdapter<br>from .claude import ClaudeAdapter<br><br># 外部导入（简洁）<br>from agent.adapter import GPTAdapter<br>`	`python<br># 外部直接导入子模块（耦合内部结构）<br>from agent.adapter.gpt.gpt_adapter import GPTAdapter<br>`
【参考】	复杂智能体场景按「生命周期」拆分包（init/run/monitor/stop）	适配大模型智能体的完整运行流程（初始化→运行→监控→停止），便于按生命周期维护代码，提升可扩展性	`<br>agent/<br>├── init/ # 初始化（模型加载、配置读取）<br>├── run/ # 运行（任务执行、模型调用）<br>├── monitor/ # 监控（性能统计、异常告警）<br>└── stop/ # 停止（资源释放、状态保存）<br>`	`<br># 无生命周期拆分（复杂场景混乱）<br>agent/<br>├── core.py # 混有初始化、运行、停止逻辑<br>`

6.4 项目管理规范（基于 uv 工具）

结合 uv 工具（现代 Python 包管理 / 虚拟环境工具，替代 pip/venv/poetry）的核心特性，对齐 Java 团队 Maven/Gradle 的项目管理习惯（依赖锁定、环境隔离、构建发布），制定以下规范，延续【强制】【推荐】【参考】分级，确保团队使用 uv 统一项目管理流程，降低环境不一致、依赖冲突问题：

规约等级	具体要求	说明	正例	反例
【强制】	必须使用`uv init`初始化项目，统一用`pyproject.toml`管理项目配置（替代 requirements.txt/setup.py）	uv 是现代 Python 项目管理工具，`uv init`生成标准`pyproject.toml`（类比 Java 的 pom.xml/gradle.build），统一项目元信息、依赖、构建配置，禁止混用老旧的 requirements.txt	`bash<br># 初始化项目（指定Python版本，对齐团队环境）<br>uv init agent-project --python 3.11<br># pyproject.toml核心配置示例<br>[project]<br>name = "agent-project"<br>version = "1.0.0"<br>dependencies = [ "requests==2.31.0", "langchain==0.1.10" ]<br>`	`bash<br># 未用uv init，仍用requirements.txt管理依赖<br>echo "requests==2.31.0" > requirements.txt<br>pip install -r requirements.txt<br>`
【强制】	必须使用`uv venv`创建项目专属虚拟环境，禁止全局安装依赖；虚拟环境目录统一命名为`.venv`，加入`.gitignore`	类比 Java 的 Maven 本地仓库隔离，避免全局依赖版本冲突；`.venv`是 uv 默认虚拟环境目录，统一命名便于团队识别	`bash<br># 创建虚拟环境（默认生成.venv目录）<br>uv venv<br># 激活虚拟环境（Linux/Mac）<br>source .venv/bin/activate<br># 激活虚拟环境（Windows）<br>.venv\Scripts\activate<br># .gitignore添加<br>.venv/<br>`	`bash<br># 全局安装依赖，无环境隔离<br>uv install requests==2.31.0 # 未激活虚拟环境，安装到全局<br># 虚拟环境命名混乱<br>uv venv agent-venv # 不同项目命名不一致<br>`
【强制】	必须使用`uv add`添加依赖，`uv lock`生成`uv.lock`并提交到仓库；禁止手动修改`uv.lock`	`uv add` 自动更新`pyproject.toml`，`uv lock`生成精准的依赖锁文件（类比 Java 的 pom.lock/gradle.lock），确保团队所有成员依赖版本完全一致；手动修改锁文件会导致依赖不一致	`bash<br># 添加生产依赖<br>uv add requests==2.31.0<br># 添加开发依赖（分组管理）<br>uv add --dev pytest==7.4.3<br># 生成锁文件<br>uv lock<br># 提交到仓库<br>git add pyproject.toml uv.lock<br>git commit -m "添加requests/pytest依赖，锁定版本"<br>`	`bash<br># 手动修改pyproject.toml添加依赖<br>vim pyproject.toml # 手动写入requests==2.31.0<br># 未生成/提交uv.lock<br>uv add requests==2.31.0<br>git add pyproject.toml # 仅提交配置文件，无锁文件<br>`
【强制】	禁止混用 uv 和 pip 安装依赖；团队成员统一用`uv sync`同步依赖（基于 pyproject.toml+uv.lock）	混用 pip/uv 会导致依赖库版本不一致、锁文件失效；`uv sync`类比 Java 的`mvn clean install`，一键同步锁文件中的依赖版本，确保环境一致	`bash<br># 新成员拉取代码后，同步依赖（自动读取lock文件）<br>uv sync<br># 仅更新单个依赖并重新锁定<br>uv add requests==2.32.0<br>uv lock<br>`	`bash<br># 混用pip安装依赖，破坏uv锁文件<br>uv sync<br>pip install requests==2.32.0 # 导致实际依赖与lock文件不一致<br>`
【强制】	必须使用`uv run`执行项目命令（如启动、测试、打包），禁止直接在激活的虚拟环境中执行	`uv run` 无需手动激活虚拟环境，直接调用`.venv`中的命令（类比 Java 的`mvn exec:java`），统一命令执行方式，避免环境激活遗漏	`bash<br># 运行测试（无需激活虚拟环境）<br>uv run pytest tests/<br># 运行项目主程序<br>uv run python agent/main.py<br>`	`bash<br># 激活虚拟环境后执行，易遗漏激活步骤<br>source .venv/bin/activate<br>pytest tests/<br>python agent/main.py<br>`
【推荐】	依赖按「生产 / 开发」分组管理，在`pyproject.toml`中用`[project.optional-dependencies]`定义；开发依赖统一放入`dev`分组	类比 Java 的 Maven profile（开发 / 生产环境依赖分离），减少生产环境依赖体积，避免开发工具（如 pytest/flake8）被打包到生产环境	`toml<br># pyproject.toml配置<br>[project]<br>name = "agent-project"<br>dependencies = [ "requests==2.31.0" ]<br><br>[project.optional-dependencies]<br>dev = [ "pytest==7.4.3", "flake8==6.1.0", "black==24.2.0" ]<br>bash<br># 安装生产依赖+开发依赖<br>uv sync --all-extras<br># 仅安装生产依赖（生产环境）<br>uv sync<br>`	`toml<br># 开发依赖混入生产依赖<br>[project]<br>dependencies = [ "requests==2.31.0", "pytest==7.4.3" ]<br>`
【推荐】	统一配置 uv 镜像源（国内优先用阿里云 / 清华源），通过`.uv.toml`或环境变量设置，禁止各自修改源	类比 Java 的 Maven settings.xml 统一镜像源，提升依赖下载速度，避免因源不同导致依赖拉取失败；`.uv.toml`放入项目根目录，团队共享配置	`toml<br># .uv.toml 统一镜像源配置<br>[registry]<br>index = "https://mirrors.aliyun.com/pypi/simple/"<br>bash<br># 或临时环境变量（CI/CD中使用）<br>UV_REGISTRY_INDEX=https://mirrors.aliyun.com/pypi/simple/ uv sync<br>`	`bash<br># 各自修改源，导致依赖拉取不一致<br>uv config set registry.index https://pypi.tuna.tsinghua.edu.cn/simple/<br>`
【推荐】	编写统一的项目脚本（`uv run -s`），封装常用命令（启动 / 测试 / 打包），放入`pyproject.toml`的`[tool.uv.scripts]`	类比 Java 的 Maven 插件命令（`mvn test`/`mvn package`），统一团队操作命令，避免记复杂指令；脚本化后新人可快速上手	`toml<br># pyproject.toml配置脚本<br>[tool.uv.scripts]<br>test = "pytest tests/ -v" # 运行测试<br>start = "python agent/main.py" # 启动项目<br>lint = "flake8 agent/ tests/" # 代码检查<br>bash<br># 执行脚本（统一命令）<br>uv run test<br>uv run start<br>`	`bash<br># 无统一脚本，各自执行不同命令<br>uv run pytest tests/ -v # 有人加-v，有人不加<br>uv run python agent/main.py --dev # 参数不统一<br>`
【推荐】	使用`uv build`构建项目包（wheel/sdist），`uv publish`发布（需配置 PyPI 凭据）；构建产物放入`dist/`，加入`.gitignore`	类比 Java 的`mvn package`构建 jar 包，`uv build`生成标准 Python 包格式，便于部署 / 发布；`dist/`为默认构建目录，统一管理产物	`bash<br># 构建项目包<br>uv build<br># 发布到PyPI（需提前配置UV_PYPI_TOKEN）<br>uv publish<br># .gitignore添加<br>dist/<br>.whl<br>.tar.gz<br>`	`bash<br># 手动打包，格式不标准<br>python setup.py sdist bdist_wheel # 未用uv build，易生成不兼容产物<br>`
【参考】	大型多模块项目使用`uv workspace`管理，在根目录`pyproject.toml`中定义 workspace，子模块独立配置	类比 Java 的 Maven 多模块项目（parent pom + 子 module），拆分大型项目为多个子模块，降低单模块复杂度；uv workspace 自动处理子模块依赖	`toml<br># 根目录pyproject.toml<br>[workspace]<br>members = [ "agent-core", "agent-api", "agent-utils" ]<br>bash<br># 根目录同步所有子模块依赖<br>uv sync<br># 进入子模块执行命令<br>cd agent-core && uv run test<br>`	`bash<br># 多模块项目无workspace，各自管理依赖<br>cd agent-core && uv sync<br>cd agent-api && uv sync # 重复操作，依赖易冲突<br>`
【参考】	CI/CD 流程中使用 uv 官方镜像（`ghcr.io/astral-sh/uv`），统一 CI 环境；缓存`uv cache`目录提升构建速度	类比 Java CI/CD 中缓存 Maven 仓库，uv cache 缓存已下载的依赖包，减少 CI/CD 重复下载；官方镜像确保 CI 环境与本地一致	yaml<br># GitHub Actions示例（CI/CD配置）<br>jobs:<br> test:<br> runs-on: ubuntu-latest<br> steps:<br> - uses: actions/checkout@v4<br> - uses: astral-sh/setup-uv@v2 # 安装uv<br> - name: Cache uv dependencies<br> uses: actions/cache@v3<br> with:<br> path: ~/.cache/uv<br> key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}<br> - run: uv sync # 同步依赖<br> - run: uv run test # 运行测试<br>	`yaml<br># CI中未用uv，仍用pip<br>steps:<br> - run: pip install -r requirements.txt<br> - run: pytest tests/<br>`

七、设计规约

7.1 核心设计原则

规约等级	具体要求	说明	正例	反例
【强制】	类 / 函数遵循单一职责原则，禁止一个类承担多个核心功能	类比 Java SOLID 原则，提升代码可维护性	`python<br># 单一职责：仅处理模型加载<br>class ModelLoader:<br> def load_config(self, model_name):<br> pass<br> def load_model(self, config):<br> pass<br><br># 单一职责：仅处理提示构建<br>class PromptBuilder:<br> def build(self, template, variables):<br> pass`	`python<br># 多职责：模型加载+提示构建+响应处理<br>class AgentUtil:<br> def load_model(self):<br> pass<br> def build_prompt(self):<br> pass<br> def handle_response(self):<br> pass`
【推荐】	大模型智能体核心逻辑抽象为接口（ABC），不同模型实现子类	类比 Java 接口 + 实现类设计，提升扩展性（适配多模型）	`python<br>from abc import ABC, abstractmethod<br><br>class LLMClient(ABC):<br> @abstractmethod<br> def generate(self, prompt: str) -> str:<br> pass<br><br>class GPTClient(LLMClient):<br> def generate(self, prompt: str) -> str:<br> # GPT实现<br> pass<br><br>class ClaudeClient(LLMClient):<br> def generate(self, prompt: str) -> str:<br> # Claude实现<br> pass`	`python<br># 无抽象，直接写死GPT实现<br>def generate(prompt: str) -> str:<br> # GPT调用逻辑<br> pass<br># 新增Claude时，需修改generate函数，违反开闭原则`
【参考】	重复逻辑提取为工具函数 / 基类，禁止复制粘贴代码	类比 Java 工具类 / 抽象基类，提升代码复用性	`python<br># 工具函数：通用字符串脱敏<br>def mask_sensitive(text: str) -> str:<br> # 脱敏逻辑<br> pass<br><br># 基类：通用模型配置加载<br>class BaseModelConfig:<br> def load_config(self, model_name):<br> # 通用加载逻辑<br> pass`	多个函数 / 类中重复编写「字符串脱敏」「配置加载」逻辑

8、总结

核心对齐点
类命名、异常命名、日志级别、工程结构等维度完全对齐 Java 规范，降低迁移成本；函数 / 变量命名贴合 Python PEP 8，但通过「语义化」要求保持与 Java 命名逻辑一致。
关键差异点
需重点关注 Python 特有规范（缩进 4 空格、默认参数不可变、with 语句、f-string），禁止用 Java 习惯编写 Python 代码（如 Tab 缩进、硬编码默认列表）。
安全与工程底线
敏感信息禁止硬编码、SQL 必须参数化、异常禁止吞掉、日志禁止用 print 替代，这四类【强制】规约是保障代码健壮性的核心。

本文来自网友投稿或网络内容，如有侵犯您的权益请联系我们删除，联系邮箱：wyl860211@qq.com 。

献给Javaer的Python开发规范

一、编程规约

1.1 命名规范

1.2 格式规范

1.3 导入规范

1.4 函数 / 方法规范

1.5 控制语句规范

1.6 数据类型规范

1.7 注释规范

二、异常日志规约

2.1 异常处理规范

2.2 日志使用规范

三、单元测试规约

3.1 测试基础规范

四、安全规约

4.1 基础安全规范

五、MySQL 数据库规约

5.1 数据库操作规范

六、工程结构规约

6.1 项目结构规范

6.2 版本控制规范

6.3 包结构规范

6.4 项目管理规范（基于 uv 工具）

七、设计规约

7.1 核心设计原则

8、总结

最新文章

热门文章

随机文章

献给Javaer的Python开发规范

一、编程规约

1.1 命名规范

1.2 格式规范

1.3 导入规范

1.4 函数 / 方法规范

1.5 控制语句规范

1.6 数据类型规范

1.7 注释规范

二、异常日志规约

2.1 异常处理规范

2.2 日志使用规范

三、单元测试规约

3.1 测试基础规范

四、安全规约

4.1 基础安全规范

五、MySQL 数据库规约

5.1 数据库操作规范

六、工程结构规约

6.1 项目结构规范

6.2 版本控制规范

6.3 包结构规范

6.4 项目管理规范（基于 uv 工具）

七、设计规约

7.1 核心设计原则

8、总结

Python每日1语法·Day6

Python考试进阶路线:从入门到专业的系统成长指南

最新文章

热门文章

随机文章