本文介绍一种基于 `groupby().cumcount()` 辅助 `merge` 的技巧，实现两个 dataframe 按“class”分组后逐行对齐拼接，生成适合 streamlit 等前端直接渲染的结构化报告表。
在构建分析型报表（尤其是面向非技术用户或需嵌入 Streamlit/Dash 等交互式界面时），数据的可读性与对齐逻辑往往比纯计算更重要。当需要将两个来源不同但语义相关的 DataFrame（如“历史订单” vs “新订单”、“基准指标” vs “实验指标”）按某一分类维度（如 class）进行“行对行”对齐展示时，标准的 pd.concat(axis=1) 会简单横向堆叠，而 pd.merge() 默认按键完全匹配，均无法满足“每类内按出现顺序逐行配对、缺失则补 NaN”的需求。
核心思路是：为每个 DataFrame 中同一 class 下的记录打上组内序号（0, 1, 2...），再以此序号 + class 作为复合键进行外连接（how='outer'）。这样就能确保：
- 同一 class 下第 1 条记录只与另一表中该 class 的第 1 条记录对齐；
- 若某类在某一表中条目更少，则对应位置自动填充 NaN；
- 所有 class 值均被保留（外连接保障）。
以下是完整实现代码：
import pandas as pd
# 构造示例数据
data1 = {'class': ['A', 'A', 'B', 'X'],
'item': ['_1', '_2', '_3', '_4'],
'value': [10, 11, 12, 13]}
data2 = {'class': ['A', 'B', 'B', 'C'],
'item': ['_5', '_6', '_7', '_8'],
'value': [20, 21, 22, 23]}
df1 = pd.DataFrame(data1)
df2 = pd.DataFrame(data2)
# 关键步骤：添加组内序号列并执行外连接
out = (df1
.merge(df2,
how='outer',
left_on=['class', df1.groupby('class').cumcount()],
right_on=['class', df2.groupby('class').cumcount()],
suffixes=('_1', '_2'))
.sort_values('class') # 按 class 排序提升可读性
.drop(columns=['key_0', 'key_1'], errors='ignore') # 清理 merge 生成的临时键列（旧版 pandas 可能为 key_0/key_1）
.reset_index(drop=True))
print(out)输出结果如下，完全符合目标格式：
class item_1 value_1 item_2 value_2 0 A _1 10.0 _5 20.0 1 A _2 11.0 NaN NaN 2 B _3 12.0 _6 21.0 3 B NaN NaN _7 22.0 4 C NaN NaN _8 23.0 5 X _4 13.0 NaN NaN
✅ 注意事项与最佳实践：
- cumcount() 返回从 0 开始的整数，天然适合作为序号键；若需从 1 开始，可用 cumcount() + 1，但两表必须保持一致。
- merge 中 left_on/right_on 接收列表，允许同时指定多个列（含动态生成的序号列），这是本方案的关键灵活性所在。
- suffixes=('_1', '_2') 明确区分来源列，避免列名冲突；建议命名体现业务含义（如 '_baseline', '_current'）。
- drop(columns=[...]) 应显式指定待删列名，并添加 errors='ignore' 防止因 pandas 版本差异导致报错（新版可能不生成 key_0/key_1）。
- 若原始数据中 class 列含空值（NaN），groupby('class') 会将其单独归为一组，需提前用 fillna() 处理以保证逻辑正确。
该方法无需循环或自定义函数，完全向量化，兼具简洁性、可读性与工程鲁棒性，是构建高质量分析报表的实用范式。
