简介：这份资源面向具备一定C#基础的开发者与IT从业者，聚焦于通过编程方式从数据库提取数据并自动生成Word文档这一常见企业级需求。包内共230个文件，以cs源码、dll程序集、pdb调试符号为主，辅以csproj工程文件、config配置、sql脚本、resx资源及少量exe与doc文档，压缩包约2.62MB，整体构成一套可直接编译运行的完整示例工程。内容围绕ADO.NET连接数据库、执行SQL查询获取表与字段信息，再借助Office Interop或NPOI、OpenXML SDK等方案将结果以表格形式写入Word文档，涵盖连接配置、查询构造、结果处理、表格填充与格式化保存等环节。已有429人学习下载，适合需要实现报告自动生成、数据分析报表或批量文档导出的读者参考，可帮助理解数据库与文档处理之间的衔接思路，并对比不同Word生成方案的取舍。
1. 从一张报表说起：程序实现数据库生成 Word 文档到底在解决什么
每月初，业务方甩过来一句“把上个月的订单明细导成 Word 给我”，如果你手动打开数据库客户端、复制结果集、粘贴到 Word、调格式、另存为，做一次还行，做十次就是灾难。程序实现数据库生成 Word 文档，本质是把「查库 → 取数 → 套模板 → 落盘」这条链路写成代码，让机器替你做重复劳动。它适合三类人：做后台管理系统的后端、需要批量出合同/报告的工具开发者、以及被 Excel 和 Word 混合排版折磨过的数据岗。核心诉求通常就两个——数据要准，格式要稳。热搜里“数据库”“word文档”反复出现，说明大家卡的不是概念，而是落地时选哪条路、参数怎么设、坑在哪。
2. 三条主流技术路线：python-docx、模板占位符、HTML 转 Word 怎么选
2.1 先想清楚：你要的是“生成”还是“填充”
很多人一上来就问用哪个库，其实先要分清场景。如果 Word 文档结构固定、只是数据在变，比如劳动合同、质检报告，那叫“模板填充”，最优解是做一个带占位符的 .docx 模板，程序只负责替换变量。如果文档结构本身随数据变化，比如订单条数不固定、要动态加表格行，那叫“程序生成”，得用代码从头构建段落和表格。还有一类是数据已经在网页或富文本里，想直接转成 Word，那就走 HTML 转 Word 的路子。选错路线，后面全是返工。
我一般这样判断：字段位置固定、样式要求高、要给非技术人员改模板 → 模板填充；结构动态、要精确控制每个单元格 → 代码生成；已有 HTML 报表想快速落地 → HTML 转换。三条路没有绝对优劣，只有匹配度。
2.2 python-docx：从零构建文档的最小可用代码
python-docx 是最常见的“程序生成”方案，它把 Word 的段落、表格、样式抽象成对象。下面这段代码演示从数据库取数并生成一份带标题和表格的 Word。
# pip install python-docx pymysql import pymysql from docx import Document from docx.shared import Pt from docx.enum.text import WD_ALIGN_PARAGRAPH # 1. 连接数据库，注意 charset 要设 utf8mb4，否则中文乱码 conn = pymysql.connect( host="127.0.0.1", port=3306, user="report", password="your_pwd", database="sales", charset="utf8mb4" ) cursor = conn.cursor() cursor.execute("SELECT order_no, customer, amount, created_at FROM orders WHERE created_at >= %s", ("2024-05-01",)) rows = cursor.fetchall() # 2. 新建文档，设置默认字体，避免中文显示成宋体以外的默认字体 doc = Document() style = doc.styles["Normal"] style.font.name = "微软雅黑" style.font.size = Pt(10.5) # 3. 标题段落，居中 title = doc.add_heading("月度订单明细", level=1) title.alignment = WD_ALIGN_PARAGRAPH.CENTER # 4. 建表格，行数 = 数据行 + 1 表头，列数固定 4 table = doc.add_table(rows=1, cols=4) table.style = "Table Grid" # 不加这行表格没有边框 hdr = table.rows[0].cells for i, text in enumerate(["订单号", "客户", "金额", "下单时间"]): hdr[i].text = text # 5. 逐行写入，注意所有值转成字符串 for r in rows: cells = table.add_row().cells cells[0].text = str(r[0]) cells[1].text = str(r[1]) cells[2].text = f"{r[2]:.2f}" cells[3].text = str(r[3]) doc.save("orders.docx") cursor.close() conn.close()逻辑说明：连接阶段charset="utf8mb4"是硬性要求，MySQL 默认 latin1 会让中文变问号。样式阶段先改Normal样式，比逐个 run 设置字体省事。表格必须显式指定Table Grid，否则默认无边框，打印出来一片空白。参数上，add_heading的 level 决定字号层级，add_table的 rows 初始给 1 行表头即可，后续用add_row()追加，不要一次性算好行数再填，容易越界。
2.3 模板占位符：让业务方自己维护 Word 样式
如果样式复杂，比如有页眉页脚、公司 logo、多级标题，用代码一点点搭非常痛苦。更稳的做法是让业务方在 Word 里做好模板，变量位置写成{{customer}}这种占位符，程序只做替换。python-docx 本身不直接支持占位符替换，因为 Word 会把一个词拆成多个 run，需要合并 run 再替换。
from docx import Document def replace_in_paragraph(paragraph, mapping): # 把段落里所有 run 的文本拼起来，整体替换后再写回第一个 run full_text = "".join(run.text for run in paragraph.runs) for key, val in mapping.items(): full_text = full_text.replace("{{" + key + "}}", str(val)) if paragraph.runs: paragraph.runs[0].text = full_text for run in paragraph.runs[1:]: run.text = "" doc = Document("contract_template.docx") data = {"customer": "张三", "amount": "12000.00", "date": "2024-06-01"} for para in doc.paragraphs: replace_in_paragraph(para, data) # 表格里的占位符同样要处理，遍历所有单元格段落 for table in doc.tables: for row in table.rows: for cell in row.cells: for para in cell.paragraphs: replace_in_paragraph(para, data) doc.save("contract_out.docx")逻辑说明：Word 的 run 是格式一致的最小文本单元，{{customer}}可能被拆成{{、customer、}}三个 run，直接对单个 run 替换会失败。先拼接再整体写回第一个 run、清空其余 run，是常见做法。参数上，占位符命名建议用英文加下划线，避免和正文冲突；替换前先备份模板，防止误改。
2.4 HTML 转 Word：已有网页报表的快速通道
当数据已经渲染成 HTML 表格，比如后台的打印预览页，可以用htmldocx这类库把 HTML 片段塞进 Word。它适合快速出结果，但样式还原度有限，复杂 CSS 会丢。常见做法是先用模板引擎渲染 HTML，再转 docx，最后人工抽查一遍分页和字体。
3. 把数据取出来：数据库连接、查询与大数据量分页
3.1 连接参数里最容易翻车的三个点
数据库连接看着简单，实际踩坑最多。第一是字符集，MySQL 要utf8mb4，PostgreSQL 一般UTF8，SQL Server 要注意排序规则。第二是超时，生成报表往往查全月数据，默认 10 秒超时不够，要显式设read_timeout。第三是只读账号，报表程序绝不要用写权限账号，避免误操作。下面是一个带超时和只读意识的连接示例。
import pymysql conn = pymysql.connect( host="10.0.0.12", port=3306, user="report_ro", # 只读账号 password="***", database="sales", charset="utf8mb4", read_timeout=120, # 读超时 120 秒 cursorclass=pymysql.cursors.DictCursor # 返回字典，按列名取值 )参数说明：read_timeout控制查询等待上限，报表场景建议 60 到 300 秒；DictCursor让结果按列名访问，代码可读性更好，但内存占用略高。如果用的是连接池，注意池大小不要超过数据库max_connections的十分之一，否则高峰期会把库拖垮。
3.2 大数据量必须分页，否则内存先炸
一次性fetchall()十万行，Python 进程内存直接飙到几百兆，Word 也扛不住。正确做法是服务端游标或分页查询，边取边写。MySQL 用LIMIT offset, size，但 offset 很大时性能差，更好的是按主键游标翻页。
def iter_orders(cursor, page_size=2000): last_id = 0 while True: cursor.execute( "SELECT id, order_no, customer, amount FROM orders " "WHERE id > %s ORDER BY id LIMIT %s", (last_id, page_size) ) rows = cursor.fetchall() if not rows: break for row in rows: yield row last_id = rows[-1]["id"]逻辑说明：用id > last_id代替 offset，避免全表扫描。page_size一般 1000 到 5000，太小网络往返多，太大单批内存高。生成 Word 时，每批数据直接写入表格，不要先攒成一个大列表。
3.3 字段类型转换：日期、金额、NULL 的处理
数据库里的datetime、decimal、NULL直接写进 Word 会出问题。日期要格式化成字符串，金额要控制小数位，NULL要显示成空或“无”。建议在取数后统一做一层转换，而不是散落在各处。
from datetime import datetime from decimal import Decimal def normalize(row): out = {} for k, v in row.items(): if v is None: out[k] = "" elif isinstance(v, datetime): out[k] = v.strftime("%Y-%m-%d %H:%M") elif isinstance(v, Decimal): out[k] = f"{v:.2f}" else: out[k] = str(v) return out这样处理后再交给文档生成层，逻辑清晰，也方便单测。
4. 避坑与排查：生成 Word 时最容易被忽略的五个问题
4.1 中文乱码：现象是问号或方块
现象：生成的 Word 里中文全变成???或方块。原因：数据库连接字符集不是utf8mb4，或者 Python 文件编码、字体设置有问题。解决：连接串加charset="utf8mb4"，文档Normal样式字体设为“微软雅黑”或“宋体”，并确认数据库表和字段本身是 utf8mb4。
4.2 表格没有边框：现象是打印出来一片白
现象：屏幕上能看到文字，打印或转 PDF 后表格线消失。原因：add_table默认样式是无边框的Table Normal。解决：显式设置table.style = "Table Grid"，或者自定义样式并确保样式存在于模板中。
4.3 占位符替换失败：现象是{{name}}原样保留
现象：模板里的占位符没被替换。原因：Word 把占位符拆成多个 run，或者占位符里有隐藏空格。解决：用前面拼接 run 的方法；同时检查模板里是否误输入了全角花括号，建议统一用半角{{ }}。
4.4 内存暴涨：现象是进程被 OOM 杀掉
现象：数据量一大，程序跑几分钟就被系统杀掉。原因：fetchall()一次性加载全部结果，或者把所有行攒在列表里再生成。解决：改用游标分页或服务端游标，边取边写，每批处理完释放引用。
4.5 文件被占用：现象是保存时报 PermissionError
现象：doc.save()报权限错误。原因：目标 Word 文件正被用户打开，Windows 下文件锁导致无法写入。解决：保存前检查文件是否存在且可写，或者生成带时间戳的文件名，避免覆盖正在编辑的文件。
5. 进阶技巧：用模板 + 分页 + 校验把方案做成可交付工具
5.1 模板与代码分离，让业务方自己改样式
把模板文件放在配置目录，代码只读模板路径。业务方要改字体、加 logo，直接改 .docx，不用动代码。占位符清单单独维护一份映射表，程序启动时校验模板里所有占位符是否都有对应数据，缺一个就报错，避免生成半成品。
5.2 分页与页眉页脚：用节（section）控制
Word 的分页靠节，python-docx 里doc.add_section(WD_SECTION.NEW_PAGE)可以新起一页。页眉页脚要针对每个节单独设置，否则会继承上一节。如果报表要“每 50 行分页”，可以在写表格时计数，到阈值就加新节并重建表头。
5.3 生成后自动校验：打开文件数表格行数
生成完不要直接交付，写一段校验逻辑：重新打开生成的 docx，统计表格行数是否等于查询行数加表头，检查关键字段是否为空。这一步能拦住 90% 的“数据少了几行”问题。
from docx import Document def verify(path, expected_rows): doc = Document(path) table = doc.tables[0] actual = len(table.rows) - 1 # 减去表头 if actual != expected_rows: raise ValueError(f"行数不符：期望 {expected_rows}，实际 {actual}") return True参数说明：expected_rows来自查询计数，校验失败直接抛异常，让任务失败而不是发出错误报表。
5.4 一个具体技巧：用域代码插入自动更新的日期
如果 Word 里需要“生成日期”，不要写死字符串，用域代码{ DATE }可以让用户打开时自动更新。python-docx 不直接支持，但可以通过在模板里预置域，程序只替换其他占位符，日期交给 Word 自己算。这样每次打开都是当天日期，省去手动改的麻烦。
我自己的习惯是：任何要发给业务方的报表，生成后一定先自己打开看三样——中文有没有乱码、表格有没有边框、行数对不对。这三样过了，再谈样式美化。希望帮到你。
本文还有配套的精品资源，点击获取
