简介这份《模块设计文档》面向项目经理、系统架构师、开发与测试人员用于在软件开发前期明确各模块的职责、接口、依赖关系与实现策略帮助团队统一设计语言、减少协作误解。文档围绕文档目的与范围、读者对象、参考文献、术语与缩写、模块命名规则、模块汇总表与关系图展开并给出子系统及其具体模块的功能描述、接口与属性、数据结构与算法等填写位置适合作为项目模块设计说明书的参考模板。资源包共1个doc文件约93KB结构完整、目录层级清晰便于按章节替换项目信息后直接使用。已有665人学习读者可从中获得模块划分、接口定义、依赖梳理和设计文档编排的具体思路为开发、测试与后续维护提供可追溯的依据。1. 从一份被退回三次的模块设计文档说起这套模板解决什么模块设计文档这个词多数人是在毕设中期检查或课程设计验收前一周才第一次认真对待。某同学代码已经跑通导师只问一句系统拆成几个模块每个模块的接口写在哪一页他答不上来因为全部逻辑堆在三个上千行的文件里。这份模板要解决的就是这件事先把系统拆成能被单独描述、单独实现、单独测试的设计单元再给每个单元规定固定的记录格式即模块名称、功能描述、接口与属性、数据结构与算法、补充说明。它适合正在做毕设或课设、需要交一份别人看得懂的设计文档的学生也适合团队里想把文档口径统一起来的开发者。文档不是代码的附属品它是你交付时唯一能证明「我想清楚了」的东西。2. 文档骨架设计02 章的元信息、读者对象与模块汇总一份模块设计文档最先被翻开的往往不是正文而是版本历史和目录。骨架没搭好后面写得再细也像是散装材料。这一章把 02 章拆开讲文件头部的元信息怎么填、0.10.4 四个小节各写什么、模块汇总表和关系图用什么形式表达。这部分工作量不大但决定了读者对整份文档的第一判断也决定了你后期改稿时有没有回头路。2.1 版本历史与文件状态先给文档上一道后悔药模板顶部那几行看起来最像形式主义文件状态勾选框、文件标识、当前版本、作者、审核、完成日期再加一张版本历史表。很多人直接留空结果答辩时评委问「这份文档改过几轮」只能说记不清了。正确的填法是让版本历史表承担变更记录的职责。每一行对应一次实质性修改备注栏写清改了什么而不是写「修改文档」这种废话。文件状态用三个勾选框控制节奏草稿阶段可以频繁改正式发布后只允许出修订版正在修改表示当前这一版不可引用。文件标识建议用「项目缩写-文档类型-序号」的形式和后面模块编号的规则保持一致。版本/状态作者审核起止日期备注v0.1 / 草稿开发A—03.01–03.05搭出 02 章骨架模块清单初稿 18 个v0.5 / 草稿开发A开发B03.06–03.12补齐子系统A 全部模块接口拆分 A-3 为 A-3、A-4v0.9 / 正在修改开发A开发B03.13–03.18按评审意见补数据结构说明与异常约定v1.0 / 正式发布开发A导师C03.19冻结基线后续变更走修订记录这张表的价值在答辩现场特别明显评委看到模块从 18 个变成 19 个会顺着问为什么拆你就有机会讲设计演进而不是被动挨问。我一般要求学生至少留三行记录哪怕项目只有两周。2.2 0.10.4 四小节目的、读者、参考文献、术语各写多少0.1 文档目的与范围最容易写成空话。合格写法是「一句话目的 两栏范围」。目的写这份文档支撑哪个阶段的什么决策范围写清包含哪些子系统、不包含哪些内容。不包含那一栏尤其重要比如「不涉及部署拓扑与数据库物理设计见部署文档」一句话就把边界划清了评审时没人会追问你没写的东西。0.2 读者对象不要只列角色名要写每个角色关心哪些章节。这张对照表花十分钟就能填完收益是整个团队知道该翻哪一页。读者重点章节想解决的问题项目负责人2.1 汇总表、5 其他模块是否覆盖全部需求谁负责哪块架构/审核人1 命名规则、2.2 关系图分层是否清晰有没有循环依赖开发人员3.n / 4.n 各模块接口签名、参数含义、异常怎么处理测试人员功能描述、补充说明边界条件、异常分支从哪构造用例0.3 参考文献按模板给的格式写标识符、作者、文献名称、出版单位或归属单位、日期。内部资料也照这个格式标「内部资料」即可。数量上三到五条够用把需求规格说明、体系结构设计、引用的标准或算法出处列上别为了凑数把搜索引擎结果页写进去。0.4 术语与缩写是整份文档性价比最高的一节。凡是正文里出现两次以上的缩写都进表。经验值是八到十五条少了说明你没认真梳理多了说明你在替读者做本该在正文解释的事。术语表还有个隐藏作用它逼你统一叫法避免同一节里「任务」和「作业」混用。2.3 模块汇总表与模块关系图一张表看清二十个模块2.1 的模块汇总表是整份文档的索引列设计直接决定可读性。我习惯用七列模块编号、模块名称、所属子系统、功能简述、责任人、依赖模块、对应源文件。功能简述控制在四十字以内写「做什么」不写「怎么做」依赖模块这一列是后面画关系图的原始数据填的时候只填直接依赖不要把间接依赖也写进去。2.2 的模块关系图模板里说参考体系结构设计文档实际交付时用分层描述加依赖矩阵最稳。分层按接入、业务、数据三层画箭头只允许从上往下指。依赖矩阵用表格表达行是调用方列是被调用方交叉格打勾。调用方 \ 被调用方A-1A-2B-1B-2A-1—A-2—B-1✓✓—B-2✓—矩阵里只要出现左下角对称位置的回勾就是循环依赖必须当场拆掉。这张表比任何图形都容易检查评审时直接扫一遍就知道结构干不干净。3. 模块命名规则与汇总表落地让代码和文档用同一套名字第 1 章模块命名规则那部分模板只给了一句提示实际写起来是最容易糊弄也最容易被抓的地方。评审老师不会逐个文件比对但他会随手翻两页看文档里的类名和代码里的类名是否一致。这一章讲三件事命名规则怎么定得住、汇总表怎么填得满、关系图怎么画得出依赖方向。3.1 命名规则怎么写才不空从类、函数、变量三层约定起命名规则的写法不是罗列「要见名知意」这种原则而是给出一张可对照的表让写代码的人和写文档的人查同一张表。最小可用集合是四类模块编号、类型名、函数名、常量名。模块编号用「子系统字母-序号」如 A-1、B-3和汇总表、正文小节标题、源文件三处保持一致。对象规则正例反例模块编号子系统字母 连字符 两位序号A-2、B-11a2、模块二类 / 结构体PascalCase名词或名词短语OrderValidatororderValidator、Validator1函数 / 方法snake_case动词开头validate_itemsitemsCheck、doIt常量UPPER_SNAKE_CASEMAX_ITEM_COUNTmaxCount源文件snake_case与模块名对应module_a2_order_validator.pyA2.py、order.py规则定完要落到代码里验证一次。下面这段不是完整实现是把命名规则和模块编号写进文件头的示例目的是让后面 3.n 节引用时能直接对应上。# 文件subsystem_a/module_a2_order_validator.py # 对应模块编号 A-2类名 PascalCase常量 UPPER_SNAKE_CASE方法 snake_case MAX_ITEM_COUNT 200 # 单笔订单商品行上限超限直接判非法 DEFAULT_STRICT_MODE False # 严格模式默认关闭兼容历史数据 class OrderValidator: # 类名用名词不加 Checker/Helper 之类后缀 def validate_items(self, items: list, strict: bool False) - dict: # 方法动词开头布尔参数加 is_/strict_ 前缀避免调用处读不懂 ...这段代码的设计说明只有一句命名规则的每一条都要能在代码里找到实例否则规则就是墙上的标语。参数items是待校验的商品行列表strict控制是否对缺失字段报错返回值为包含ok与errors两个键的字典。文件头注释里的模块编号是硬约束代码评审时第一眼看的就是它和汇总表对不对得上。3.2 模块汇总表的列设计名称、功能简述、责任人、依赖汇总表填不满通常不是模块少而是粒度没定。模板里对模块的定义是「相对独立的软件设计单元例如对象类、函数包」这句话给了你选择权但选择权要配上判断标准否则有人把整个子系统当一个模块有人把一个工具函数也单列一行。我一般用三条标准筛能单独分配责任人、能单独写测试用例、能单独说清输入输出。三条同时满足才进表。按这个标准一个中等规模的课设项目通常在 12 到 25 个模块之间低于 10 个说明你拆得不够高于 30 个说明你在把函数当模块。责任人这一列在团队项目里是刚需在个人项目里也别空着写自己的代号即可它提醒你每个模块都要有人兜底。依赖模块只填直接调用方间接依赖由关系图推导两处信息不要重复维护否则改一处忘一处是必然的。3.3 模块关系图的画法分层、依赖方向与禁止反向依赖关系图的常见翻车是把所有调用关系都画上去最后变成一团毛线。可交付的画法是先定层再画线接入层负责接收请求和参数转换业务层放各子系统的核心模块数据层负责持久化和外部接口封装。层级确定后依赖方向就只有自上而下一种。具体到子系统A、子系统B的划分跨子系统调用只允许发生在业务层之间且必须经由对方暴露的接口模块不允许直接调用对方内部模块。这条规则写进 2.2 的图注里比画一百条箭头都管用。图注还要写明当前版本的已知例外比如「B-2 暂直接依赖 A-1 的返回结构计划在下个版本改为经 A-4 转换」把技术债摆到明面上评审时反而是加分项。4. 子系统模块设计功能描述、接口与属性、数据结构与算法第 3 章和第 4 章是文档的主体模板给每个模块固定了五段模块名称、功能描述、接口与属性、数据结构与算法、补充说明。这五段不是随便排的它对应读者从「这是什么」到「怎么调」再到「为什么这么设计」的认知顺序。这一章按这个顺序讲每一段写到什么颗粒度附一个可以照着改的模块样例。4.1 每个 3.n 小节的固定五段式模块名称一行必须和汇总表、源文件三处一致编号在前名称在后例如「A-2 订单校验器」。功能描述写三句话这个模块做什么、不做什么、被调用时的前置条件。第二句最容易被省略但它恰恰是划分模块边界的证据。比如「不负责商品库存扣减库存校验在 B-1 完成」一句话就把职责边界钉死了。接口与属性这一段分两块。接口列函数或方法每个都要有功能说明、输入参数、输出参数、返回值、异常。属性列模块内部持有的状态写清类型、初值、生命周期。模板提示里说「用专业的设计工具设计接口与属性此处粘贴即可」实际交付时贴图不如贴签名签名能被搜索、能被 diff、能贴进代码评审。数据结构与算法这一段只要模块里用了非平凡结构就必须写。判断标准很简单如果换一个开发者接手他会不会因为看不懂这里的结构而改错。会就写。补充说明放边界条件、兼容性约束、未决项未决项要标责任人和计划关闭时间别让「待定」两个字在文档里过夜。4.2 接口与属性函数签名、参数、返回值、异常一个都不能少接口描述最典型的偷懒写法是「输入订单数据输出校验结果」。这种描述在联调时等于没写因为调用方不知道字段名、不知道空值怎么处理、不知道失败时是抛异常还是返回错误码。合格的写法是签名加参数表再补一段异常约定。class OrderValidator: A-2 订单校验器校验商品行合法性不做库存与价格计算。 def __init__(self, max_items: int MAX_ITEM_COUNT) - None: self._max_items max_items # 构造期固定模块内只读 def validate_items(self, items: list, strict: bool False) - dict: 校验商品行。返回 {ok: bool, errors: list[dict]}。 # 行数为空或超上限时直接返回错误不进入逐行校验 ...参数说明按表来items是字典列表必填单行必须含sku_id与count两个键strict为布尔值默认False为真时缺失可选字段也记错误返回字典中errors每项包含row、code、message三个字段。异常约定单独写一句入参类型错误抛TypeError业务校验失败不抛异常一律通过返回值表达。这条约定决定了调用方写不写 try必须显式写出来。属性部分同样要写清。上面的_max_items属于构造期注入的只读属性文档里要注明「运行期不可修改如需调整请重新实例化」否则总有人在中途赋值然后奇怪为什么行为不一致。4.3 数据结构与算法写到能复现设计决策的颗粒度这一段的目的是解释选择不是抄教科书。写四件事就够用了什么结构、为什么不用更常见的那个、关键操作的时间复杂度、边界情况怎么处理。下面以子系统A 里的任务队列模块为例。import heapq class TaskQueue: A-3 任务队列按优先级出队容量固定满队列拒绝入队。 def __init__(self, capacity: int 1024) - None: self._capacity capacity # 容量上限构造期固定 self._heap [] # 小顶堆元素为 (priority, seq, task) self._seq 0 # 单调递增序号保证同优先级先进先出 def push(self, task: dict, priority: int 5) - bool: if len(self._heap) self._capacity: return False # 满队列不抛异常由调用方决定降级策略 self._seq 1 heapq.heappush(self._heap, (priority, self._seq, task)) return True设计说明要讲透两点。第一为什么用小顶堆而不是有序链表入队和出队都是 O(log n)而有序链表插入是 O(n)在任务量上千时差距明显。第二为什么要加_seq序号优先级相同时元组比较会继续比较第三个元素task字典无法比较会直接抛异常加一个单调序号既解决比较问题又顺带保证了同优先级先进先出。这种「不写就会踩坑」的细节正是数据结构与算法这一段存在的意义。边界情况写三条容量为 0 时构造即拒绝所有入队priority允许为负数表示紧急任务出队在队列为空时返回None而不是抛异常与入队风格保持一致。4.4 补充说明边界条件、兼容性与未决项补充说明不是垃圾桶它有固定内容。第一类是兼容性老版本数据结构怎么迁移接口加参数时默认值取什么。第二类是性能约束单次调用允许的最大耗时、批量处理的上限条数写数字不写「较快」。第三类是未决项当前版本没想清楚的问题写清现象、可选方案、责任人和关闭时间。未决项在毕设文档里往往被藏起来其实它是最好用的答辩素材。评委最怕的是学生觉得自己的设计完美无缺你敢列三条未决项并说清取舍反而证明你知道边界在哪。我一般建议每个子系统留一到两条多了显得没做完一条没有显得没想过。5. 避坑与排查模块设计文档最容易翻车的四个点写文档的过程里有些错误几乎每份初稿都会出现而且不是笔误是方法问题。这一章列四个最高频的翻车点每条按现象、原因、解决三段写。看的时候可以对照自己的稿子中一条就回去改一版比通读十篇范文有用。5.1 坑一命名规则写了三套文档一套代码一套口头一套现象是文档里写类名用 PascalCase代码里一半是下划线一半是驼峰汇总表里的模块编号又从 A-2 变成了 ModuleA2。评审时随便抽一个模块对照三处对不上整份文档的可信度直接归零。原因通常是命名规则在项目启动时定了一次中途有人图快就近改了名没人回头同步。文档和代码是两份独立维护的资产没有强制关联漂移是必然的。解决办法是把模块编号做成硬关联源文件头注释写编号汇总表写编号正文小节标题写编号三处任意一处改动都要全量搜索替换。命名规则表放在文档第 1 章同时截一份放进代码仓库的贡献说明里让写代码的人不用翻文档也能看到。评审前跑一次全局搜索把所有不符合规则的标识符列出来能改的改改不了的进未决项。5.2 坑二模块粒度失控要么一个模块写三页要么三十个模块各三行现象是汇总表里有的模块功能描述写了五行还说不完有的只有一句「工具类」。前者其实是三个模块粘在一起后者根本不该独立成模块。原因是拆分时没有统一标准凭感觉切。写文档的人往往按代码文件切一个文件一个模块结果工具函数文件也成了一个模块核心业务文件反而因为太长被拆成好几节。解决办法是回到三条标准能单独分配责任人、能单独写测试用例、能单独说清输入输出。三条不满足的合并或下沉满足的即使代码只有五十行也单列。拆完在汇总表里数一遍模块数落在 12 到 25 之间基本合理超出范围就重新过一遍标准。另外模块粒度一旦在 v1.0 冻结后续变更必须走版本历史不要悄悄改。5.3 坑三接口只写输入输出异常和空值全靠猜现象是联调时调用方问「这个字段能传空吗」「失败是抛异常还是返回 null」文档里一个字都没有只能翻代码。翻了代码发现作者自己也没统一有的地方抛异常有的地方返回空字典。原因是写接口描述时只想着正常路径异常路径被默认成「不会发生」。实际上联调时间的一半都花在异常路径上。解决办法是在接口段固定加三行空值与缺省怎么处理、失败怎么表达、哪些情况会抛异常。这三行写成模板句式每个接口都填填不出来说明这个接口还没设计完。同时把返回值结构写死比如统一返回带ok与errors的字典让调用方不需要针对每个接口写不同的错误处理。这一条改起来最费时间但收益也最大。5.4 坑四文档写完就锁进文件夹实现变了文档不动现象是答辩前三天打开文档发现里面写的模块 A-3 已经在重构时删了接口参数从两个变成四个文档还停留在初稿。评委问一句「这个参数现在还有吗」场面会很尴尬。原因是写作和开发是两条时间线文档只在开头写一次之后没有任何触发更新的机制。很多人把文档当交付物交完就完事忘了它首先是给团队看的工具。解决办法是把文档更新挂到开发流程上每次接口变更必须同步改对应小节并升版本号代码评审时把「文档是否同步」列为检查项。个人项目没有评审就用一个笨办法每周五下午花二十分钟对照汇总表把本周改过的模块过一遍改完在版本历史里记一行。这个习惯看着土但它能保证你在答辩前不需要通宵补文档。6. 验收与答辩用一份评审清单把文档讲成方案文档写完只是及格线能不能过验收看的是你能不能在被追问时接得住。我在带项目的过程中总结出一张评审清单自己先过一遍比等评委挑毛病强。检查项合格标准常见扣分点三处一致汇总表、正文标题、源文件头的模块编号完全对应编号跳号、重号、大小写不一模块粒度模块数在 1225 之间每个模块三条标准全满足工具类单列、业务模块合并接口完整每个接口有空值、失败、异常三行约定只写输入输出异常靠猜数据结构每个非平凡结构写了选择理由与复杂度只贴代码不写为什么依赖方向依赖矩阵无反向勾选跨子系统只走接口模块循环依赖、跨层直调版本可追溯版本历史至少三行备注写清改了什么只有一行初稿记录未决项每个子系统一到两条带责任人一条没有或列了不闭环答辩时的五分钟讲法也有套路。第一分钟讲范围这份文档覆盖哪两个子系统、多少个模块、不覆盖什么。第二分钟讲结构三层划分、依赖方向、为什么这么切。第三分钟挑一个模块深入最好是那个有算法取舍的把「为什么不用更常见的结构」讲清楚。第四分钟讲未决项和已知技术债主动交代边界。最后一分钟留给提问提前准备三个高频问题的答案模块为什么这么多、循环依赖怎么处理的、接口改了文档怎么同步。我吃过一次亏文档写得挺全但答辩时被问到「A-3 和 B-2 谁先调用谁」翻了三分钟没找到最后靠记忆答的。从那以后我每次交付前都强制走一遍依赖矩阵把每一行每一列的勾选逐个念一遍念不通的地方就是没想清楚的地方。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/29 11:15:15 · 阅读 1.2k 模块设计文档模板：模块拆分、接口设计与依赖评审
简介这份《模块设计文档》面向项目经理、系统架构师、开发与测试人员用于在软件开发前期明确各模块的职责、接口、依赖关系与实现策略帮助团队统一设计语言、减少协作误解。文档围绕文档目的与范围、读者对象、参考文献、术语与缩写、模块命名规则、模块汇总表与关系图展开并给出子系统及其具体模块的功能描述、接口与属性、数据结构与算法等填写位置适合作为项目模块设计说明书的参考模板。资源包共1个doc文件约93KB结构完整、目录层级清晰便于按章节替换项目信息后直接使用。已有665人学习读者可从中获得模块划分、接口定义、依赖梳理和设计文档编排的具体思路为开发、测试与后续维护提供可追溯的依据。1. 从一份被退回三次的模块设计文档说起这套模板解决什么模块设计文档这个词多数人是在毕设中期检查或课程设计验收前一周才第一次认真对待。某同学代码已经跑通导师只问一句系统拆成几个模块每个模块的接口写在哪一页他答不上来因为全部逻辑堆在三个上千行的文件里。这份模板要解决的就是这件事先把系统拆成能被单独描述、单独实现、单独测试的设计单元再给每个单元规定固定的记录格式即模块名称、功能描述、接口与属性、数据结构与算法、补充说明。它适合正在做毕设或课设、需要交一份别人看得懂的设计文档的学生也适合团队里想把文档口径统一起来的开发者。文档不是代码的附属品它是你交付时唯一能证明「我想清楚了」的东西。2. 文档骨架设计02 章的元信息、读者对象与模块汇总一份模块设计文档最先被翻开的往往不是正文而是版本历史和目录。骨架没搭好后面写得再细也像是散装材料。这一章把 02 章拆开讲文件头部的元信息怎么填、0.10.4 四个小节各写什么、模块汇总表和关系图用什么形式表达。这部分工作量不大但决定了读者对整份文档的第一判断也决定了你后期改稿时有没有回头路。2.1 版本历史与文件状态先给文档上一道后悔药模板顶部那几行看起来最像形式主义文件状态勾选框、文件标识、当前版本、作者、审核、完成日期再加一张版本历史表。很多人直接留空结果答辩时评委问「这份文档改过几轮」只能说记不清了。正确的填法是让版本历史表承担变更记录的职责。每一行对应一次实质性修改备注栏写清改了什么而不是写「修改文档」这种废话。文件状态用三个勾选框控制节奏草稿阶段可以频繁改正式发布后只允许出修订版正在修改表示当前这一版不可引用。文件标识建议用「项目缩写-文档类型-序号」的形式和后面模块编号的规则保持一致。版本/状态作者审核起止日期备注v0.1 / 草稿开发A—03.01–03.05搭出 02 章骨架模块清单初稿 18 个v0.5 / 草稿开发A开发B03.06–03.12补齐子系统A 全部模块接口拆分 A-3 为 A-3、A-4v0.9 / 正在修改开发A开发B03.13–03.18按评审意见补数据结构说明与异常约定v1.0 / 正式发布开发A导师C03.19冻结基线后续变更走修订记录这张表的价值在答辩现场特别明显评委看到模块从 18 个变成 19 个会顺着问为什么拆你就有机会讲设计演进而不是被动挨问。我一般要求学生至少留三行记录哪怕项目只有两周。2.2 0.10.4 四小节目的、读者、参考文献、术语各写多少0.1 文档目的与范围最容易写成空话。合格写法是「一句话目的 两栏范围」。目的写这份文档支撑哪个阶段的什么决策范围写清包含哪些子系统、不包含哪些内容。不包含那一栏尤其重要比如「不涉及部署拓扑与数据库物理设计见部署文档」一句话就把边界划清了评审时没人会追问你没写的东西。0.2 读者对象不要只列角色名要写每个角色关心哪些章节。这张对照表花十分钟就能填完收益是整个团队知道该翻哪一页。读者重点章节想解决的问题项目负责人2.1 汇总表、5 其他模块是否覆盖全部需求谁负责哪块架构/审核人1 命名规则、2.2 关系图分层是否清晰有没有循环依赖开发人员3.n / 4.n 各模块接口签名、参数含义、异常怎么处理测试人员功能描述、补充说明边界条件、异常分支从哪构造用例0.3 参考文献按模板给的格式写标识符、作者、文献名称、出版单位或归属单位、日期。内部资料也照这个格式标「内部资料」即可。数量上三到五条够用把需求规格说明、体系结构设计、引用的标准或算法出处列上别为了凑数把搜索引擎结果页写进去。0.4 术语与缩写是整份文档性价比最高的一节。凡是正文里出现两次以上的缩写都进表。经验值是八到十五条少了说明你没认真梳理多了说明你在替读者做本该在正文解释的事。术语表还有个隐藏作用它逼你统一叫法避免同一节里「任务」和「作业」混用。2.3 模块汇总表与模块关系图一张表看清二十个模块2.1 的模块汇总表是整份文档的索引列设计直接决定可读性。我习惯用七列模块编号、模块名称、所属子系统、功能简述、责任人、依赖模块、对应源文件。功能简述控制在四十字以内写「做什么」不写「怎么做」依赖模块这一列是后面画关系图的原始数据填的时候只填直接依赖不要把间接依赖也写进去。2.2 的模块关系图模板里说参考体系结构设计文档实际交付时用分层描述加依赖矩阵最稳。分层按接入、业务、数据三层画箭头只允许从上往下指。依赖矩阵用表格表达行是调用方列是被调用方交叉格打勾。调用方 \ 被调用方A-1A-2B-1B-2A-1—A-2—B-1✓✓—B-2✓—矩阵里只要出现左下角对称位置的回勾就是循环依赖必须当场拆掉。这张表比任何图形都容易检查评审时直接扫一遍就知道结构干不干净。3. 模块命名规则与汇总表落地让代码和文档用同一套名字第 1 章模块命名规则那部分模板只给了一句提示实际写起来是最容易糊弄也最容易被抓的地方。评审老师不会逐个文件比对但他会随手翻两页看文档里的类名和代码里的类名是否一致。这一章讲三件事命名规则怎么定得住、汇总表怎么填得满、关系图怎么画得出依赖方向。3.1 命名规则怎么写才不空从类、函数、变量三层约定起命名规则的写法不是罗列「要见名知意」这种原则而是给出一张可对照的表让写代码的人和写文档的人查同一张表。最小可用集合是四类模块编号、类型名、函数名、常量名。模块编号用「子系统字母-序号」如 A-1、B-3和汇总表、正文小节标题、源文件三处保持一致。对象规则正例反例模块编号子系统字母 连字符 两位序号A-2、B-11a2、模块二类 / 结构体PascalCase名词或名词短语OrderValidatororderValidator、Validator1函数 / 方法snake_case动词开头validate_itemsitemsCheck、doIt常量UPPER_SNAKE_CASEMAX_ITEM_COUNTmaxCount源文件snake_case与模块名对应module_a2_order_validator.pyA2.py、order.py规则定完要落到代码里验证一次。下面这段不是完整实现是把命名规则和模块编号写进文件头的示例目的是让后面 3.n 节引用时能直接对应上。# 文件subsystem_a/module_a2_order_validator.py # 对应模块编号 A-2类名 PascalCase常量 UPPER_SNAKE_CASE方法 snake_case MAX_ITEM_COUNT 200 # 单笔订单商品行上限超限直接判非法 DEFAULT_STRICT_MODE False # 严格模式默认关闭兼容历史数据 class OrderValidator: # 类名用名词不加 Checker/Helper 之类后缀 def validate_items(self, items: list, strict: bool False) - dict: # 方法动词开头布尔参数加 is_/strict_ 前缀避免调用处读不懂 ...这段代码的设计说明只有一句命名规则的每一条都要能在代码里找到实例否则规则就是墙上的标语。参数items是待校验的商品行列表strict控制是否对缺失字段报错返回值为包含ok与errors两个键的字典。文件头注释里的模块编号是硬约束代码评审时第一眼看的就是它和汇总表对不对得上。3.2 模块汇总表的列设计名称、功能简述、责任人、依赖汇总表填不满通常不是模块少而是粒度没定。模板里对模块的定义是「相对独立的软件设计单元例如对象类、函数包」这句话给了你选择权但选择权要配上判断标准否则有人把整个子系统当一个模块有人把一个工具函数也单列一行。我一般用三条标准筛能单独分配责任人、能单独写测试用例、能单独说清输入输出。三条同时满足才进表。按这个标准一个中等规模的课设项目通常在 12 到 25 个模块之间低于 10 个说明你拆得不够高于 30 个说明你在把函数当模块。责任人这一列在团队项目里是刚需在个人项目里也别空着写自己的代号即可它提醒你每个模块都要有人兜底。依赖模块只填直接调用方间接依赖由关系图推导两处信息不要重复维护否则改一处忘一处是必然的。3.3 模块关系图的画法分层、依赖方向与禁止反向依赖关系图的常见翻车是把所有调用关系都画上去最后变成一团毛线。可交付的画法是先定层再画线接入层负责接收请求和参数转换业务层放各子系统的核心模块数据层负责持久化和外部接口封装。层级确定后依赖方向就只有自上而下一种。具体到子系统A、子系统B的划分跨子系统调用只允许发生在业务层之间且必须经由对方暴露的接口模块不允许直接调用对方内部模块。这条规则写进 2.2 的图注里比画一百条箭头都管用。图注还要写明当前版本的已知例外比如「B-2 暂直接依赖 A-1 的返回结构计划在下个版本改为经 A-4 转换」把技术债摆到明面上评审时反而是加分项。4. 子系统模块设计功能描述、接口与属性、数据结构与算法第 3 章和第 4 章是文档的主体模板给每个模块固定了五段模块名称、功能描述、接口与属性、数据结构与算法、补充说明。这五段不是随便排的它对应读者从「这是什么」到「怎么调」再到「为什么这么设计」的认知顺序。这一章按这个顺序讲每一段写到什么颗粒度附一个可以照着改的模块样例。4.1 每个 3.n 小节的固定五段式模块名称一行必须和汇总表、源文件三处一致编号在前名称在后例如「A-2 订单校验器」。功能描述写三句话这个模块做什么、不做什么、被调用时的前置条件。第二句最容易被省略但它恰恰是划分模块边界的证据。比如「不负责商品库存扣减库存校验在 B-1 完成」一句话就把职责边界钉死了。接口与属性这一段分两块。接口列函数或方法每个都要有功能说明、输入参数、输出参数、返回值、异常。属性列模块内部持有的状态写清类型、初值、生命周期。模板提示里说「用专业的设计工具设计接口与属性此处粘贴即可」实际交付时贴图不如贴签名签名能被搜索、能被 diff、能贴进代码评审。数据结构与算法这一段只要模块里用了非平凡结构就必须写。判断标准很简单如果换一个开发者接手他会不会因为看不懂这里的结构而改错。会就写。补充说明放边界条件、兼容性约束、未决项未决项要标责任人和计划关闭时间别让「待定」两个字在文档里过夜。4.2 接口与属性函数签名、参数、返回值、异常一个都不能少接口描述最典型的偷懒写法是「输入订单数据输出校验结果」。这种描述在联调时等于没写因为调用方不知道字段名、不知道空值怎么处理、不知道失败时是抛异常还是返回错误码。合格的写法是签名加参数表再补一段异常约定。class OrderValidator: A-2 订单校验器校验商品行合法性不做库存与价格计算。 def __init__(self, max_items: int MAX_ITEM_COUNT) - None: self._max_items max_items # 构造期固定模块内只读 def validate_items(self, items: list, strict: bool False) - dict: 校验商品行。返回 {ok: bool, errors: list[dict]}。 # 行数为空或超上限时直接返回错误不进入逐行校验 ...参数说明按表来items是字典列表必填单行必须含sku_id与count两个键strict为布尔值默认False为真时缺失可选字段也记错误返回字典中errors每项包含row、code、message三个字段。异常约定单独写一句入参类型错误抛TypeError业务校验失败不抛异常一律通过返回值表达。这条约定决定了调用方写不写 try必须显式写出来。属性部分同样要写清。上面的_max_items属于构造期注入的只读属性文档里要注明「运行期不可修改如需调整请重新实例化」否则总有人在中途赋值然后奇怪为什么行为不一致。4.3 数据结构与算法写到能复现设计决策的颗粒度这一段的目的是解释选择不是抄教科书。写四件事就够用了什么结构、为什么不用更常见的那个、关键操作的时间复杂度、边界情况怎么处理。下面以子系统A 里的任务队列模块为例。import heapq class TaskQueue: A-3 任务队列按优先级出队容量固定满队列拒绝入队。 def __init__(self, capacity: int 1024) - None: self._capacity capacity # 容量上限构造期固定 self._heap [] # 小顶堆元素为 (priority, seq, task) self._seq 0 # 单调递增序号保证同优先级先进先出 def push(self, task: dict, priority: int 5) - bool: if len(self._heap) self._capacity: return False # 满队列不抛异常由调用方决定降级策略 self._seq 1 heapq.heappush(self._heap, (priority, self._seq, task)) return True设计说明要讲透两点。第一为什么用小顶堆而不是有序链表入队和出队都是 O(log n)而有序链表插入是 O(n)在任务量上千时差距明显。第二为什么要加_seq序号优先级相同时元组比较会继续比较第三个元素task字典无法比较会直接抛异常加一个单调序号既解决比较问题又顺带保证了同优先级先进先出。这种「不写就会踩坑」的细节正是数据结构与算法这一段存在的意义。边界情况写三条容量为 0 时构造即拒绝所有入队priority允许为负数表示紧急任务出队在队列为空时返回None而不是抛异常与入队风格保持一致。4.4 补充说明边界条件、兼容性与未决项补充说明不是垃圾桶它有固定内容。第一类是兼容性老版本数据结构怎么迁移接口加参数时默认值取什么。第二类是性能约束单次调用允许的最大耗时、批量处理的上限条数写数字不写「较快」。第三类是未决项当前版本没想清楚的问题写清现象、可选方案、责任人和关闭时间。未决项在毕设文档里往往被藏起来其实它是最好用的答辩素材。评委最怕的是学生觉得自己的设计完美无缺你敢列三条未决项并说清取舍反而证明你知道边界在哪。我一般建议每个子系统留一到两条多了显得没做完一条没有显得没想过。5. 避坑与排查模块设计文档最容易翻车的四个点写文档的过程里有些错误几乎每份初稿都会出现而且不是笔误是方法问题。这一章列四个最高频的翻车点每条按现象、原因、解决三段写。看的时候可以对照自己的稿子中一条就回去改一版比通读十篇范文有用。5.1 坑一命名规则写了三套文档一套代码一套口头一套现象是文档里写类名用 PascalCase代码里一半是下划线一半是驼峰汇总表里的模块编号又从 A-2 变成了 ModuleA2。评审时随便抽一个模块对照三处对不上整份文档的可信度直接归零。原因通常是命名规则在项目启动时定了一次中途有人图快就近改了名没人回头同步。文档和代码是两份独立维护的资产没有强制关联漂移是必然的。解决办法是把模块编号做成硬关联源文件头注释写编号汇总表写编号正文小节标题写编号三处任意一处改动都要全量搜索替换。命名规则表放在文档第 1 章同时截一份放进代码仓库的贡献说明里让写代码的人不用翻文档也能看到。评审前跑一次全局搜索把所有不符合规则的标识符列出来能改的改改不了的进未决项。5.2 坑二模块粒度失控要么一个模块写三页要么三十个模块各三行现象是汇总表里有的模块功能描述写了五行还说不完有的只有一句「工具类」。前者其实是三个模块粘在一起后者根本不该独立成模块。原因是拆分时没有统一标准凭感觉切。写文档的人往往按代码文件切一个文件一个模块结果工具函数文件也成了一个模块核心业务文件反而因为太长被拆成好几节。解决办法是回到三条标准能单独分配责任人、能单独写测试用例、能单独说清输入输出。三条不满足的合并或下沉满足的即使代码只有五十行也单列。拆完在汇总表里数一遍模块数落在 12 到 25 之间基本合理超出范围就重新过一遍标准。另外模块粒度一旦在 v1.0 冻结后续变更必须走版本历史不要悄悄改。5.3 坑三接口只写输入输出异常和空值全靠猜现象是联调时调用方问「这个字段能传空吗」「失败是抛异常还是返回 null」文档里一个字都没有只能翻代码。翻了代码发现作者自己也没统一有的地方抛异常有的地方返回空字典。原因是写接口描述时只想着正常路径异常路径被默认成「不会发生」。实际上联调时间的一半都花在异常路径上。解决办法是在接口段固定加三行空值与缺省怎么处理、失败怎么表达、哪些情况会抛异常。这三行写成模板句式每个接口都填填不出来说明这个接口还没设计完。同时把返回值结构写死比如统一返回带ok与errors的字典让调用方不需要针对每个接口写不同的错误处理。这一条改起来最费时间但收益也最大。5.4 坑四文档写完就锁进文件夹实现变了文档不动现象是答辩前三天打开文档发现里面写的模块 A-3 已经在重构时删了接口参数从两个变成四个文档还停留在初稿。评委问一句「这个参数现在还有吗」场面会很尴尬。原因是写作和开发是两条时间线文档只在开头写一次之后没有任何触发更新的机制。很多人把文档当交付物交完就完事忘了它首先是给团队看的工具。解决办法是把文档更新挂到开发流程上每次接口变更必须同步改对应小节并升版本号代码评审时把「文档是否同步」列为检查项。个人项目没有评审就用一个笨办法每周五下午花二十分钟对照汇总表把本周改过的模块过一遍改完在版本历史里记一行。这个习惯看着土但它能保证你在答辩前不需要通宵补文档。6. 验收与答辩用一份评审清单把文档讲成方案文档写完只是及格线能不能过验收看的是你能不能在被追问时接得住。我在带项目的过程中总结出一张评审清单自己先过一遍比等评委挑毛病强。检查项合格标准常见扣分点三处一致汇总表、正文标题、源文件头的模块编号完全对应编号跳号、重号、大小写不一模块粒度模块数在 1225 之间每个模块三条标准全满足工具类单列、业务模块合并接口完整每个接口有空值、失败、异常三行约定只写输入输出异常靠猜数据结构每个非平凡结构写了选择理由与复杂度只贴代码不写为什么依赖方向依赖矩阵无反向勾选跨子系统只走接口模块循环依赖、跨层直调版本可追溯版本历史至少三行备注写清改了什么只有一行初稿记录未决项每个子系统一到两条带责任人一条没有或列了不闭环答辩时的五分钟讲法也有套路。第一分钟讲范围这份文档覆盖哪两个子系统、多少个模块、不覆盖什么。第二分钟讲结构三层划分、依赖方向、为什么这么切。第三分钟挑一个模块深入最好是那个有算法取舍的把「为什么不用更常见的结构」讲清楚。第四分钟讲未决项和已知技术债主动交代边界。最后一分钟留给提问提前准备三个高频问题的答案模块为什么这么多、循环依赖怎么处理的、接口改了文档怎么同步。我吃过一次亏文档写得挺全但答辩时被问到「A-3 和 B-2 谁先调用谁」翻了三分钟没找到最后靠记忆答的。从那以后我每次交付前都强制走一遍依赖矩阵把每一行每一列的勾选逐个念一遍念不通的地方就是没想清楚的地方。希望帮到你。本文还有配套的精品资源点击获取