Huigr王1. 从"能跑"到"可交付"的认知跃迁
我第一次提交代码时，组长看完只说了一句："这代码确实能跑"。当时还沾沾自喜，直到凌晨两点被线上告警吵醒，才发现自己写的"能跑"代码在并发场景下就像纸糊的房子。这段经历让我明白：工程师的成年礼，是从写出能运行的代码到产出可交付的解决方案。
可交付代码（Deliverable Code）与临时脚本的根本区别在于它需要经受四个维度的考验：
- 时间维度：三个月后其他人能否快速理解？
- 空间维度：在测试/预发/生产环境表现是否一致？
- 变化维度：需求变更时是否容易引发雪崩效应？
- 协作维度：是否遵循团队约定且便于CI/CD流水线处理？
某电商系统的惨痛案例：促销活动时，一个"能跑"的订单查询接口在QPS达到2000时响应时间从50ms飙升到15秒，事后排查发现开发者在for循环里执行了N+1查询。这就是典型的"能跑"陷阱——在开发环境的小数据量下一切正常，却埋下了生产环境的定时炸弹。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码质量清单的工程化实践
2.1 静态质量守门员
我在团队推行的第一道防线是静态检查清单，这些规则会通过IDE插件实时提示：
java复制// 反面教材：存在多个隐患
public List<User> getUsers(String ids) {
String[] idArr = ids.split(",");
List<User> users = new ArrayList();
for(String id : idArr) {
users.add(userDao.getById(Integer.parseInt(id))); // ①未判空 ②未捕获NumberFormatException ③N+1查询
}
return users;
}
// 优化后版本
public List<User> getUsers(@NotNull String ids) {
if (StringUtils.isBlank(ids)) {
return Collections.emptyList();
}
return Arrays.stream(ids.split(","))
.map(id -> {
try {
return userDao.getWithCache(Integer.parseInt(id.trim()));
} catch (NumberFormatException e) {
log.warn("Invalid user id: {}", id);
return null;
}
})
.filter(Objects::nonNull)
.collect(Collectors.toList());
}
关键检查项：
- 所有参数必须显式标注
@Nullable或@NotNull - Stream API优先于传统循环
- 数据库访问必须通过缓存层
- 异常处理要保留上下文信息
2.2 动态质量检测体系
静态检查只能解决30%的问题，我们还需要运行时防护：
python复制# 性能测试检查清单示例
def test_order_query_performance():
# 预热
query_order(limit=10)
# 基准测试
start = time.time()
for _ in range(1000):
query_order(limit=100)
elapsed = time.time() - start
# 断言平均响应时间<50ms且无内存泄漏
assert elapsed < 5.0
assert memory_usage() < 1024 * 1024 * 100 # <100MB
必须包含的测试类型：
- 边界测试：处理空列表/超大数值等边界值
- 并发测试：使用
jemeter模拟至少3倍生产流量 - 幂等测试：重复操作是否产生副作用
- 故障注入：模拟数据库连接超时等情况
3. 持续交付流水线中的质量门禁
3.1 Git提交规范与检查
我们团队使用Husky+Commitlint构建提交防护网：
bash复制# 提交时自动触发的pre-commit钩子
#!/bin/sh
npm run lint &&
npm run test:coverage &&
npx commitlint --edit $1
提交消息必须符合Angular规范：
code复制feat(订单): 增加批量查询接口 [JIRA-1234]
• 使用Redis缓存优化查询性能
• 添加并发控制机制
• 补充Swagger文档
3.2 CI阶段的质量关卡
GitLab CI的典型配置：
yaml复制stages:
- lint
- build
- test
- deploy
code_quality:
stage: lint
image: sonarsource/sonar-scanner-cli
script:
- sonar-scanner -Dsonar.projectKey=my_project
allow_failure: false # 必须通过
performance_test:
stage: test
script:
- jmeter -n -t load_test.jmx -l report.jtl
- python check_performance.py # 验证是否满足SLA
artifacts:
paths:
- report.jtl
关键质量阈值：
- 单元测试覆盖率≥80%
- 静态扫描0致命漏洞
- 性能测试达标率100%
- 构建产物包含完整的API文档
4. 可交付代码的隐性要求
4.1 文档即代码
我坚持文档与代码同仓库管理，使用Swagger+YAML实现活文档：
yaml复制# 在代码中维护的API文档
paths:
/users/{id}:
get:
tags:
- 用户管理
parameters:
- $ref: '#/components/parameters/userId'
responses:
200:
description: 用户详情
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
example: 123
name:
type: string
example: "张三"
文档完整性检查项：
- 所有接口必须有Swagger注解
- 复杂算法需要流程图说明
- 数据库变更要记录Flyway脚本
- 配置项需说明取值范围和默认值
4.2 可观测性设计
生产环境代码必须内置监控探针：
go复制// Gin框架的监控埋点示例
func MonitorMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
path := c.FullPath()
// 处理请求
c.Next()
// 记录指标
status := c.Writer.Status()
duration := time.Since(start)
metrics.ApiDuration.
WithLabelValues(path, strconv.Itoa(status)).
Observe(duration.Seconds())
if status >= 500 {
metrics.ErrorCount.
WithLabelValues(path).
Inc()
}
}
}
必须采集的黄金指标：
- 请求量（QPS）
- 错误率（Error Rate）
- 响应时间（P99 Latency）
- 资源利用率（CPU/Memory）
5. 质量清单的持续演进
技术债看板是我们团队的质量罗盘，使用JIRA管理三类问题：
- 立即修复：影响核心功能的缺陷（红色标签）
- 迭代优化：代码异味但暂不影响运行（黄色标签）
- 长期跟踪：架构级改进点（蓝色标签）
每双周我们会进行代码考古（Code Archaeology）：
- 随机抽取5个旧提交进行CR
- 用SonarQube对比质量趋势
- 更新检查清单中的规则
最近一次考古发现的典型问题：
- 过度使用
@SuppressWarnings注解 - 测试用例缺少断言
- 日志未脱敏敏感信息
这些发现促使我们在清单中新增了：
- 所有警告必须处理而非压制
- 测试断言覆盖率检查
- 自动化的日志脱敏过滤器
维护代码质量就像打理花园——需要定期除草（清理坏代码）、施肥（重构优化）、防治病虫害（预防缺陷）。我随身携带的检查清单已迭代到第14版，每次更新都代表着我们团队对"可交付"标准的新认知。记住：今天在代码质量上多花1小时，未来可能节省100小时的故障排查时间。