developer-onboarding-doc

开发者入职文档技能

为服务或团队编写一份完整的开发者入职文档，涵盖新工程师在入职第一周内高效开展工作所需的一切信息。

好的入职文档不是维基内容的堆砌，而是按照新工程师第一天实际会提出问题的顺序，逐一解答这些问题。

必需输入

如果尚未提供，请询问以下信息：

• 服务名称及其功能
• 负责团队
• 技术栈——语言、框架、数据库、消息队列等
• 主要外部依赖项——上游服务、第三方 API
• 部署目标——Kubernetes、ECS、Lambda、裸机等
• 本地开发环境配置——如何在本地运行（Docker Compose、本地数据库等）
• 测试方法——单元测试、集成测试、端到端测试；测试命令
• 部署流程——代码如何部署到生产环境的概要
• 值班安排——谁负责值班、告警如何工作
• 联系人——技术负责人、平台团队、相关服务负责人

输出格式

---

开发者入职指南：[服务名称]

团队： [团队名称] | 技术负责人： [姓名] 最后更新： [日期] | 更新者： [姓名]

如果本文档中有错误或内容过时，请立即修正——这会影响之后每一位入职的工程师。

---

此服务的功能

[用 3–5 句话说明此服务解决什么问题、由谁调用、它会调用谁，以及此服务宕机会导致什么问题。]

服务类型： [API / 后台工作进程 / 事件消费者 / 数据管道等] 使用方： [列出依赖此服务的内部服务或外部客户端] 依赖项： [列出此服务调用的上游服务、数据库和第三方 API]

架构图： [链接或嵌入——即使是粗略的 ASCII 图也有帮助]

[Caller A] ──→ [This Service] ──→ [Database]
                      │
                      └──→ [Downstream Service]

---

代码库概览

代码仓库： [链接] 主分支： [main / master] 语言： [例如 Go 1.22 / Node.js 20 / Python 3.12] 框架： [例如 Express / FastAPI / Gin / Rails]

关键目录

[repo-root]/
├── [src/ or cmd/]          # Application code
│   ├── [handlers/]         # HTTP handlers / controllers
│   ├── [services/]         # Business logic
│   ├── [repository/]       # Database access layer
│   └── [models/]           # Data models / types
├── [tests/]                # Test files
├── [migrations/]           # Database migrations
├── [scripts/]              # Utility scripts
├── [.github/workflows/]    # CI/CD pipeline definitions
└── [docs/]                 # Additional documentation

建议从这里开始阅读： [指出最适合了解项目的 2–3 个关键文件，例如 main.go、routes.js、app.py]

可能让你感到意外的事项

• [不寻常的模式 1——例如“我们使用事件溯源——状态由事件日志推导而来，而不是直接存储”]
• [不寻常的模式 2——例如“身份验证由网关处理——此服务信任 X-User-Id 标头”]
• [不直观的设计决策或遗留选择等不寻常的模式 3]

---

本地开发环境配置

预计配置时间： [全新机器需要 X 分钟]

先决条件

• [工具 1]——版本 [X]——[安装链接]
• [工具 2]——版本 [X]——[安装链接]
• 访问[代码仓库 / 内部包注册表]——向[负责人]申请
• [所需的密钥或凭据]——向[负责人]申请

分步配置

# 1. Clone the repo
git clone [repo URL]
cd [repo-name]

# 2. Copy and configure environment variables
cp .env.example .env
# Edit .env — see "Environment Variables" section below

# 3. Start dependencies (database, cache, etc.)
[docker compose up -d / make deps / etc.]

# 4. Install dependencies
[npm install / go mod download / pip install -r requirements.txt]

# 5. Run database migrations
[migration command]

# 6. Start the service
[start command]

# 7. Verify it's working
curl http://localhost:[PORT]/health
# Expected: {"status":"ok"}

如果无法正常运行： 请查看[下方的故障排查章节]，或在 #[channel] 中提问。

环境变量

变量	必需	描述	示例
DATABASE_URL	是	主数据库的连接字符串	postgres://localhost:5432/[db]
[VAR_2]	是	[描述]	[示例]
[VAR_3]	否	[描述——默认值]	[示例]

本地开发所需密钥： [获取方式——例如“运行 [command] 从 Vault 拉取”，或“在 #[channel] 中联系[人员]”]

常用本地命令

[start command]           # Start the service
[test command]            # Run all tests
[lint command]            # Run linter
[format command]          # Format code
[migration command]       # Run pending migrations
[seed command]            # Seed local database

---

测试

测试理念： [例如“我们在集成层进行测试——纯函数使用单元测试，任何涉及数据库或外部服务的逻辑都使用集成测试”]

运行测试

# All tests
[test command]

# Unit tests only
[unit test command]

# Integration tests (requires local deps running)
[integration test command]

# A specific test file or test case
[test command with filter]

测试覆盖率： [X]%（通过 CI 所需的最低覆盖率：[Y]%） 覆盖率报告： [查看位置]

编写测试

• 单元测试： [放置位置——例如，与源文件放在一起，命名为 *_test.go]
• 集成测试： [放置位置——例如，tests/integration/]
• 测试数据库： [运行方式——例如，“每个测试都会获得一个干净的事务，并在拆卸时回滚——参见 tests/helpers/db.go”]
• 模拟： [规则——例如，“我们在仓储层进行模拟；不要直接模拟数据库”]

---

进行更改

分支

[分支命名规范——例如，feature/[ticket-id]-short-description、fix/[ticket-id]-short-description]

提交 PR 前

• 本地测试通过
• Linter 检查通过（[lint command]）
• 新行为有测试覆盖
• 所有新增环境变量均已添加到 .env.example 并记录说明
• 数据库迁移向后兼容（旧代码可以使用新架构运行）

代码审查

• 审查者： [需要邀请谁审查——例如，“[team] 的任意工程师；涉及身份验证的更改必须由负责人审查”]
• 预期审查时间： [X 小时 / 1 个工作日]
• PR 模板： [链接或由 GitHub 自动生成]

数据库迁移

# Create a new migration
[migration create command]

# Apply pending migrations
[migration up command]

# Roll back last migration
[migration down command]

迁移规则：

• 所有迁移都必须向后兼容——旧代码必须能够使用新架构运行
• 绝不要在单次迁移中重命名或删除列——分两步完成（添加新列、迁移数据、删除旧列）
• 合并前测试回滚

---

部署

代码如何发布到生产环境： [用 1–2 句话概述——如果有完整的 CI/CD 操作手册，请附上链接]

1. 合并到 main → 自动部署到预发布环境
2. 在预发布环境运行冒烟测试
3. 手动批准 → 部署到生产环境
4. 部署后监控 [X 分钟]

部署文档： [CI/CD 操作手册或流水线文档链接]

谁可以部署： [任何工程师 / 负责人 / 值班工程师——请注明]

部署频道： #[deployments channel]

---

监控与可观测性

仪表板： [Datadog / Grafana / CloudWatch——链接] 日志： [日志聚合工具及链接——例如，“日志位于 Datadog 的 service:[name] 下”] 追踪： [追踪工具及链接（如适用）] 告警： [告警发送位置——例如 PagerDuty / Slack #alerts-[service]]

需要了解的关键指标：

• 错误率： 应低于 <[X]%（达到 [Y]% 时告警）
• P99 延迟： 应低于 <[X]ms
• [业务指标]： [例如，“队列深度应低于 100 项”]

---

值班

值班安排： [PagerDuty / Opsgenie 链接] 当前值班人员： [当前排班链接或 #oncall 频道] 升级路径： [值班人员 → [team lead] → [EM]——未确认 [X] 分钟后升级]

收到告警时：

1. 确认告警
2. 查看 [dashboard link] 寻找第一个线索
3. 常见告警的操作手册：[oncall-runbook 链接或 runbook-writer 输出]
4. 如果在 [X 分钟] 内无法解决，请升级给 [person/channel]

---

关键联系人

角色	姓名	最佳联系途径
技术负责人	[Name]	Slack：@[handle]
值班轮班	[Team]	PagerDuty / #on-call
平台 / 基础设施	[Team]	#platform Slack 频道
数据库 / DBA	[Name or team]	#database Slack 频道
[上游服务]负责人	[Name]	Slack：@[handle]

提问渠道：

• 工程相关问题：#engineering
• 关于此服务的问题：#[service-name]
• 紧急 / 生产环境问题：#incidents

---

故障排除

“服务无法在本地启动”

1. 检查 Docker / 依赖项是否正在运行：[command]
2. 检查 .env 是否已填写——缺少值会导致静默故障
3. 检查日志：[log command]
4. 在 #[channel] 中提问

“测试在本地失败，但在 CI 中通过”

• 检查本地依赖项版本是否与 CI 一致：[version check command]
• 尝试全新安装：[clean install command]
• 集成测试需要本地依赖项正在运行——[start deps command]

“我无法访问 [内部工具 / 系统]”

• 通过 [申请流程——例如 Okta 自助服务 / 询问经理] 请求访问权限

“生产环境似乎出了问题”

1. 查看 [dashboard]，确认错误是否激增
2. 在 #deployments 中查看近期部署
3. 如果是正在发生的事故，通过 [PagerDuty / Slack command] 通知值班人员

---

延伸阅读

• 架构决策记录（ADR） — 说明代码库为何如此设计
• API 文档 或 [外部文档链接]
• 事故处理手册
• CI/CD 流水线文档
• 团队协作约定

---

质量检查

• 本地设置说明在全新机器上可正常使用 — 最近已测试
• 环境变量表完整且准确
• “可能让你感到意外的事项”涵盖了实际会遇到的意外情况（可询问近期入职的成员）
• 值班部分包含真实链接，而非占位符
• 联系人信息是最新的 — 包含团队成员真实的 Slack 用户名
• 故障排查涵盖新成员最常提出的 3 个实际问题

反面模式

• 不要记录理想的设置方式 — 应记录实际设置；真实存在的怪异之处和易踩的坑，才是新工程师最需要了解的
• 不要留下“询问你的经理”之类的占位联系人 — 应为每个领域列出具体人员，否则新成员有紧急问题时，这份文档就毫无用处
• 不要在未与近期入职的成员一起审阅的情况下编写入职文档 — 作者往往意识不到哪些内容是自己想当然的
• 不要写入所有架构细节 — 面面俱到的入职文档反而什么也教不会；应链接到更深入的文档
• 不要跳过“可能让你感到意外的事项”一节 — 未记录的不明显模式，是导致第一周工程时间白白浪费的首要原因

示例触发语

• “为此服务编写一份开发者指南。”
• “为此服务编写 README。”
• “为新工程师编写一份入职文档。”
• “帮助新开发者了解代码库。”