系列写了50多篇，内容覆盖了从入门到架构的方方面面，但有一个话题一直没系统讲过：团队协作时的开发规范。
如果你是一个人写流程，命名随便、注释不写、版本乱存，问题不大——自己记得住就行。但一旦团队有2个人以上协作，或者流程需要交给别人维护，没有规范的代码就是一场灾难。
今天把开发规范讲透：命名怎么统一、注释怎么写、版本怎么管理、代码怎么审查。适合团队协作，也适合“未来的自己”回来改代码时能看懂。
规范的价值：一个反例
假设你接手了这样一个流程：
# 变量名：a, b, c, temp, data
# 子流程名：流程1, 流程2, 新建流程3
# 没有注释
# 没有日志
你能看懂吗？你敢改吗？大概率不敢动，只能重写。
写规范的代码不是为了别人，是为了3个月后的你自己。
第一部分：命名规范
1. 流程命名
| 类型 | 格式 | 示例 | 说明 |
|---|---|---|---|
| 主流程 | [业务名]_Main | PriceMonitor_Main | 入口流程，只做调度 |
| 采集子流程 | Fetch_[数据源] | Fetch_Taobao、Fetch_Pinduoduo | 采集类 |
| 清洗子流程 |
Clean_[数据集] | Clean_ProductData | 清洗类 |
| 输出子流程 | Write_[目标] | Write_Feishu、Write_Excel | 输出类 |
| 通用子流程 | Common_[功能] | Common_Wait、Common_Retry | 复用工具 |
| 配置子流程 | Config_[类型] | Config_Load | 配置加载 |
2. 变量命名
| 类型 | 格式 | 示例 | 说明 |
|---|---|---|---|
| 列表 | [复数名词]_list | product_list、order_list | 明确是列表 |
| 字典 | [名词]_dict | config_dict、product_dict | 明确是字典 |
| 数字 | [名词]_[单位] | page_num、price_value | 带单位说明 |
| 字符串 | [名词]_str | keyword_str、url_str | 可省略 |
| 布尔 | is_[状态] | is_logged_in、has_next_page | 疑问句形式 |
| 计数器 | [名词]_count | success_count、error_count | 明确是计数 |
| 临时变量 | temp_[用途] | temp_price、temp_row | 明确用途 |
| 全局变量 | G_[变量名] | G_DATA_PATH、G_CONFIG | 大写G前缀 |
3. 浏览器环境命名（Profile）
[平台]_[账号标识]_[用途]
示例：
- Taobao_Main_Collect
- Pinduoduo_ShopA_Order
- Xiaohongshu_Test
4. 文件命名
| 文件类型 | 格式 | 示例 |
|---|---|---|
| 配置文件 | config_[用途].xlsx | config_accounts.xlsx |
| 输出文件 | [业务]_[日期].xlsx | product_data_2026-07-01.xlsx |
| 日志文件 | log_[日期].xlsx | log_2026-07-01.xlsx |
| 截图文件 | error_[时间戳].png | error_202607011030.png |
第二部分：注释规范
1. 子流程文件头注释
每个子流程开头必须有注释块：
# ============================================
# 子流程：Fetch_Taobao
# 职责：从淘宝采集商品列表数据
# 输入参数：
# - keyword: 文本类型，搜索关键词
# - max_pages: 数字类型，最大翻页数
# 输出参数：
# - product_list: 列表类型，采集到的商品数据
# - status: 文本类型，"success" 或 "failed"
# 依赖子流程：
# - Common_Wait
# - Common_RetryClick
# 修改记录：
# - 2026-07-01 林焱 初始版本
# - 2026-07-15 张三 增加重试机制
# ============================================
2. 指令块注释
每个逻辑块前加简短说明：
# ----- 1. 打开搜索页面 -----
打开网页("https://www.taobao.com")
等待元素加载("//input[@id='q']", 超时时间=10秒)
# ----- 2. 输入关键词并搜索 -----
输入文本("//input[@id='q']", keyword)
点击元素("//button[@class='search-btn']")
# ----- 3. 等待搜索结果加载 -----
等待元素加载("//div[@class='product-list']", 超时时间=10秒)
3. 复杂逻辑注释
对于容易混淆的逻辑，加上注释说明：
# 注意：这里用contains匹配class，因为class名是动态生成的
获取相似元素列表("//div[contains(@class,'product-item')]", 存入列表=items)
# 索引从0开始，写入Excel时用 idx+1 计算行号
按列表循环(items, 循环项=item, 循环索引=idx):
excel_row = idx + 1
# ...
结束循环
4. 不写“废话”注释
# ❌ 废话注释
# 打开网页
打开网页("https://www.baidu.com")
# ✅ 有价值注释
# 打开百度首页，用于输入搜索关键词
打开网页("https://www.baidu.com")
第三部分：流程结构规范
1. 主流程结构
主流程只做调度，不包含具体采集逻辑：
# ============================================
# 主流程：PriceMonitor_Main
# ============================================
输出日志("===== 流程开始 =====")
# 1. 加载配置
调用子流程(Config_Load)
# 2. 执行采集
调用子流程(Fetch_Taobao)
调用子流程(Fetch_Pinduoduo)
# 3. 清洗数据
调用子流程(Clean_Data)
# 4. 输出结果
调用子流程(Write_Report)
调用子流程(Send_Notification)
输出日志("===== 流程结束 =====")
2. 子流程结构
每个子流程统一结构：
1. 文件头注释
2. 进入日志
3. Try块（主体逻辑）
- 分步骤执行
- 关键节点加日志
4. Catch块（异常处理）
- 记录错误
- 截图（如果必要）
5. Finally块（收尾）
- 关闭资源
- 清理临时文件
6. 退出日志
3. 异常处理规范
# ✅ 分模块Try-Catch，而不是整个流程包一个Try
# 每个独立的操作单元用单独的Try
Try:
登录操作()
Catch:
输出日志("【错误】登录失败")
# 登录失败通常需要停止流程
抛出异常("登录失败")
EndTry
Try:
采集操作()
Catch:
输出日志("【错误】采集失败，跳过该条数据")
# 采集失败可以继续
继续循环
EndTry
第四部分：版本管理
1. 流程版本号
每次重大修改更新版本号：
V1.0 - 初始版本
V1.1 - 增加重试机制
V1.2 - 适配淘宝页面改版
V2.0 - 重构为模板化架构
2. 配置文件版本
# 在配置文件中加一行版本信息
配置表:
| 配置项 | 配置值 |
|--------|--------|
| config_version | 2.1 |
| last_update | 2026-07-01 |
3. 修改记录
每次修改后，在流程的注释块中记录：
# 修改记录：
# - 2026-07-01 林焱 V1.0 初始版本
# - 2026-07-15 张三 V1.1 增加超时重试
# - 2026-08-01 林焱 V2.0 适配新页面结构
第五部分：代码审查清单
提交代码前，逐条确认：
流程结构
- 子流程有文件头注释
- 主流程只做调度，不含具体逻辑
- 每个子流程有进入/退出日志
- 关键操作有Try-Catch
命名
- 子流程名符合命名规范
- 变量名有意义（不是a/b/c/temp）
- 浏览器环境名符合规范
注释
- 复杂逻辑有注释说明
- 没有“废话”注释
- XPath有说明是捕获什么元素
可维护性
- 敏感信息不在代码中硬编码
- 路径使用配置文件或相对路径
- 流程在其他电脑上能直接跑（不依赖本地特有文件）
团队协作建议
分工模式
| 角色 | 职责 | 输出 |
|---|---|---|
| 架构师 | 设计整体架构、制定规范 | 架构文档、规范文档 |
| 开发A | 采集层子流程 | 各平台采集子流程 |
| 开发B | 清洗层+存储层 | Python清洗代码 |
| 开发C | 交付层 | 看板、告警、报表 |
| 测试 | 验证流程稳定性 | 测试报告 |
协作工具
| 用途 | 推荐工具 |
|---|---|
| 代码存储 | Git（流程文件是XML格式，可版本控制） |
| 文档 | 飞书/语雀 |
| 任务管理 | 飞书任务/Trello |
| 沟通 | 企业微信/飞书 |
常见问题速查
| 问题 | 解决方法 |
|---|---|
| 团队多人修改同一流程冲突 | 用Git分支管理，每人一个分支 |
| 新人不熟悉规范 | 把规范文档放在项目根目录 |
| 流程在其他电脑跑不起来 | 检查路径是否用了绝对路径 |
| 不知道流程是谁写的 | 文件头注释加作者信息 |
推荐资源
- Git入门教程（网上很多）
- 影刀官方《流程开发规范》文档
- 本系列第36篇《流程模板化与复用策略》
#影刀RPA #RPA自动化 #开发规范 #团队协作 #代码审查
作者：林焱
本文为《影刀RPA学习手册》系列文章之一，内容源于实操经验的整理与分享。