在协作中成长，在细节中精进

软件工程实践总结

目录

一、课程回顾与总结

1. 成长与抒怀

这门软件工程课是我大学以来最具颠覆性的一次学习体验。过去，我习惯把“完成功能”等同于“项目成功”——只要代码能跑、结果正确，就算大功告成。然而，这门课通过真实团队项目彻底重塑了我的认知：“能跑只是起点，可靠、可维护、可协作才是终点”。

在项目开发中，我作为辅助开发，没有负责核心业务逻辑的编码，却前所未有地深入理解了“质量内建”（Quality Built-in）的含义。我参与了从需求澄清、接口验证、边界测试到文档整理的完整流程，逐渐意识到：一个真正可用、可靠、可持续演进的系统，70% 的功夫不在“写”，而在“想”和“验”。

我虽然没写核心业务逻辑，但通过测试、文档、边界 case 梳理，我第一次感受到“质量不是测出来的，是设计出来的”。

2. 深入思考的问题

问题一：辅助开发的价值究竟是什么？我是否只是“打杂”？

初始困惑：
项目初期，我一度担心自己的角色边缘化。主开发在写 UploadRule、ReviewEvent 这些核心接口，而我似乎只在“跑测试”，“写文档”，“整理随笔”——这些工作看起来琐碎、重复，甚至“可有可无”。

厘清过程：
我的认知转变始于一次真实的 bug 发现。
在测试“管理员查看学生材料”接口时，主开发的逻辑是：根据前端传入的 college 参数过滤数据。我立刻意识到风险：如果恶意用户传入其他学院 ID，是否能越权查看？于是构造测试用例，果然绕过了权限控制。这个漏洞被及时修复，并推动团队确立新规范：所有涉及数据隔离的接口，必须从 JWT 中提取用户所属学院，禁止依赖前端传参。

此外，在整理“积分规则查询”接口文档时，我发现 Thrift 定义的字段是 recognized_event_id，而 Go 结构体生成的是 RecognizedEventID。虽然 hz 工具自动加了 json:"recognized_event_id" 标签，但前端若按 Go 字段名调用会失败。我标注并同步给前端同学，避免了前后端联系的冲突。

新理解：
辅助开发绝非打杂。我们从外部视角、用户视角、攻击者视角审视系统，暴露主开发者因“沉浸式编码”而忽略的盲区。我们的价值不在于产出多少行代码，而在于让系统在交付前就具备抗脆弱性。

问题二：文档真的是“形式主义”吗？为什么团队总把文档排在最后？

初始认知：
在以往课程项目中，我们往往在 deadline 前几小时草草拼凑一份“接口列表”，内容多为 GET /api/user 返回用户信息。我认为“代码即文档”，只要结构清晰，别人能看懂。

转变契机：
在冲刺第三天，团队要联调“ES 全文搜索”功能。主开发实现了 SearchItems 接口，但未说明：

（1）哪些字段支持模糊搜索？（赛事名称、主办方）

（2）ID 查询是否精确匹配？

（3）时间格式要求？

前端同学按经验传了 eventName，但实际字段是 RecognizedEventName（来自 Thrift）。双方花了近 2 小时排查，最终发现是命名风格不一致导致。那一刻我意识到：没有文档的接口，极易导致冲突。

行动与收获：
我主动提出：每完成一个接口，立即生成标准化文档草稿。借助 AI 技术员，我根据 Thrift IDL 和 Hertz 路由注解，自动生成包含以下内容的接口说明：

路径与方法，请求参数（字段名、类型、是否必填、示例），响应结构（成功/失败），典型错误码

主开发采纳后，后续接口联调效率显著提升。

结论：
好的文档不是负担，而是协作的“契约”。它让团队成员在不同时间、不同角色下，对系统有统一认知。

3. 五个阶段的最大收获

4. 团队项目心得

本次团队项目让我深刻体会到：软件工程的本质是“降低协作成本”。

角色互补：主开发梁伟彬专注构建系统骨架（如积分计算引擎、ES 同步逻辑），我则聚焦验证地基是否牢固（如权限，边界，文档）。这种分工让团队效率最大化。

信息透明：我们通过每日 15 分钟站会，只同步三件事：昨天做了什么、今天计划做什么、当前卡点是什么。这确保问题不过夜。

工具赋能：我们用 AI 技术员统一随笔格式、生成文档草稿、梳理测试用例，将重复劳动自动化，把人力留给创造性工作。

最让我感动的是，主开发从不认为我的反馈是“挑刺”，而是真诚欢迎每一个能提升系统健壮性的建议。这种开放、信任的协作氛围，是项目成功的关键。

5. 七大课程目标自评（百分制）

二、个人技术总结

在“准备篇”中，我为自己制定了学习路线：深入 Go 后端开发，掌握 API 测试与接口验证。本次团队项目中，我担任辅助开发，主要解决以下技术问题：

（1）验证 Hertz 接口参数绑定与校验逻辑

（2）梳理 Thrift IDL 与 Go 模型的字段映射一致性

（3）设计破坏性测试用例并推动修复

我选择以下技术进行深入总结：

[个人技术总结: Go + Hertz 框架下基于 Thrift IDL 的接口测试与字段映射一致性验证](个人技术总结：Go + Hertz 框架下基于 Thrift IDL 的接口测试与字段映射一致性验证-CSDN社区)

概述：
在 CloudWeGo Hertz 项目中，Thrift IDL 是前后端接口契约。hz update 工具根据 IDL 生成 Go 结构体、路由和绑定逻辑。然而，因命名风格（IDL 蛇形 vs Go 驼峰）、可选字段（optional）、嵌套结构等差异，极易出现“字段存在但无法绑定”或“前端传对字段却收不到值”的问题。本文总结如何通过自动化比对与结构化测试，确保 IDL 与实现层字段映射 100% 一致。

三、软件开发模式

1. 项目开发过程

• 项目目标：开发高校竞赛积分认定系统，支持学院/专业管理、赛事认定配置、学生材料提交、管理员审核、积分自动计算、学院/全校排行榜、ES 全文检索、用户反馈查看。
• 技术栈：Go 1.22 + CloudWeGo Hertz + MySQL + Elasticsearch (olivere/elastic/v7) + JWT + Thrift IDL
• 关键决策：
  • 接口契约：采用 Thrift IDL，确保前后端字段、类型、必填性一致
  • 权限模型：辅导员角色通过 JWT 透传 college，Service 层统一注入过滤条件
  • 积分计算：Beta 阶段采用“审核通过即同步计算”，优先保证闭环，标记后续优化为异步
  • 数据同步：认定事件变更时，手动调用 ES AddItem/RemoveItem，并记录后续需引入 MQ 保证一致性
• 挑战与解决方案：
  • ES 与 MySQL 数据不一致风险 → 在 Service 层关键路径显式调用 ES 同步，并添加错误日志
  • 权限越权漏洞 → 禁止前端传 college，所有过滤基于 JWT 解析结果
  • 驳回理由无法统计 → 提议后续增加 reject_reason_type 枚举字段

2. 软件开发模式分析

我们采用 Scrum 敏捷开发，具体实践如下：

• 每日站会：15 分钟同步进展、卡点，不讨论细节
• 任务拆解：按“接口 + 测试 + 文档”三位一体拆分，主辅开发结对协作
• 持续交付：每日结束时确保当日功能可演示、可测试

优点：

快速反馈闭环：问题在当日暴露、当日解决，避免堆积
聚焦用户价值：优先实现“认定→审核→积分”核心链路
角色灵活互补：辅助开发可快速切入测试与文档

缺点：

技术债显性化：如 ES 一致性、驳回原因结构化等问题被标记“后续优化”，若无迭代计划易被遗忘
文档初期滞后：初期未同步更新接口说明，导致联调阻塞
测试覆盖不全：因时间紧张，仅覆盖主路径和关键边界，未做全量异常测试

3. 软件开发模式对比与建议

模式选择建议

• 需求明确稳定、技术成熟、合同驱动型项目（如政府系统、嵌入式固件） → 优先选瀑布模型**
• 需求模糊、需快速验证可行性或用户交互逻辑（如创新产品、UI/UX 探索） → 优先选快速原型模型
• 中大型项目、需提前交付核心功能并控制风险（如企业 ERP、电商平台） → 优先选增量模型
• 高风险、高复杂度、高可靠性要求的大型项目（如航空航天、金融核心系统） → 优先选螺旋模型
• 互联网产品、需求多变、强调快速试错与市场响应（如社交 App、SaaS 工具） → 优先选敏捷开发
• 需求大致明确、但需通过多轮反馈逐步完善（如内部管理系统、教育平台） → 优先选迭代模型

4. 个人思考

开发模式不是教条，而是适配工具。我们的选择基于三个现实：

时间约束→ 必须优先交付可演示功能

学习目标→ 需覆盖完整开发流程

团队规模→ 沟通成本低，适合高度协作的敏捷

如果项目延续至生产环境，我会建议：

在敏捷中嵌入“文档门禁”：PR 必须包含接口更新说明，否则不合并

设立“技术债看板”：明确每项 debt 的负责人和解决时间

引入自动化测试：用脚本验证 Thrift 与 Go 字段映射一致性

最终，最好的开发模式，是让团队成员每天下班时，都清楚“明天做什么”且“今天的问题已闭环”。本次开发，我们做到了。