universal-dev-standards 5.17.0 → 6.0.0

package/bundled/locales/zh-CN/options/project-structure/swift.md

@@ -0,0 +1,165 @@
+---
+source: options/project-structure/swift.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+# Swift 项目结构
+
+> **语言**: [English](../../../../options/project-structure/swift.md) | 简体中文
+
+**上层标准**: [项目结构](../../core/project-structure.md)
+
+---
+
+## 概览
+
+Swift 项目可使用 Swift Package Manager (SPM) 或 Xcode 来管理。iOS/macOS 应用程序通常使用 Xcode 项目，而库与服务器端 Swift 则使用 SPM。
+
+## 项目类型
+
+### SPM Library
+
+```
+project-root/
+├── Sources/
+│   └── PackageName/
+│       ├── PackageName.swift
+│       ├── Models/
+│       ├── Services/
+│       └── Utilities/
+├── Tests/
+│   └── PackageNameTests/
+│       └── PackageNameTests.swift
+├── Package.swift
+└── README.md
+```
+
+### SPM Executable
+
+```
+project-root/
+├── Sources/
+│   ├── AppName/
+│   │   └── main.swift
+│   └── AppNameCore/
+│       └── Core.swift
+├── Tests/
+│   └── AppNameTests/
+├── Package.swift
+└── README.md
+```
+
+### iOS App
+
+```
+project-root/
+├── AppName/
+│   ├── App/
+│   │   ├── AppNameApp.swift
+│   │   └── ContentView.swift
+│   ├── Features/
+│   │   ├── Home/
+│   │   │   ├── HomeView.swift
+│   │   │   └── HomeViewModel.swift
+│   │   └── Settings/
+│   ├── Core/
+│   │   ├── Models/
+│   │   ├── Services/
+│   │   └── Utilities/
+│   ├── Resources/
+│   │   ├── Assets.xcassets
+│   │   └── Localizable.strings
+│   └── Info.plist
+├── AppNameTests/
+├── AppNameUITests/
+├── AppName.xcodeproj
+└── README.md
+```
+
+### Vapor（服务器端）
+
+```
+project-root/
+├── Sources/
+│   ├── App/
+│   │   ├── configure.swift
+│   │   ├── routes.swift
+│   │   ├── Controllers/
+│   │   ├── Models/
+│   │   └── Migrations/
+│   └── Run/
+│       └── main.swift
+├── Tests/
+│   └── AppTests/
+├── Resources/
+│   └── Views/
+├── Public/
+├── Package.swift
+└── docker-compose.yml
+```
+
+## 配置文件
+
+| 文件 | 用途 | Required |
+|------|------|----------|
+| `Package.swift` | Swift Package Manager manifest | Yes (SPM) |
+| `*.xcodeproj` | Xcode 项目 | Yes (Xcode) |
+| `*.xcworkspace` | Xcode workspace | No |
+| `.swiftlint.yml` | SwiftLint 配置 | No |
+| `.swift-version` | Swift 版本 | No |
+
+## .gitignore
+
+```
+.build/
+.swiftpm/
+*.xcodeproj/xcuserdata/
+*.xcworkspace/xcuserdata/
+DerivedData/
+.DS_Store
+Pods/
+Carthage/
+```
+
+## 工具
+
+| 类别 | 工具 |
+|------|------|
+| Build | Swift Package Manager, Xcode, xcodebuild |
+| Test Runner | XCTest, Quick/Nimble |
+| Linter | SwiftLint, SwiftFormat |
+| Formatter | SwiftFormat, swift-format |
+| Package Manager | Swift Package Manager, CocoaPods, Carthage |
+| Documentation | DocC, Jazzy |
+
+## 规则
+
+| 规则 | 描述 | Priority |
+|------|------|----------|
+| Feature folders | 按功能分组，包含 View、ViewModel 与 Models | Recommended |
+| SPM targets | 将 library 与 executable 拆分为不同的 target | Recommended |
+| Protocol-oriented | 使用 protocol 进行抽象与依赖注入 | Recommended |
+| Test naming | 使用 `test_methodName_condition_expectedResult` 格式 | Recommended |
+| Access control | 使用最小访问级别（默认为 internal，API 才用 public） | Required |
+
+## 相关选项
+
+- [Kotlin](./kotlin.md) - Kotlin 项目结构
+- [Rust](./rust.md) - Rust 项目结构
+
+---
+
+## 参考资料
+
+- [Swift Package Manager](https://swift.org/package-manager/)
+- [Apple Developer Documentation](https://developer.apple.com/documentation/)
+- [Vapor](https://vapor.codes/)
+
+---
+
+## 许可
+
+本文档以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。
+
+**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/options/testing/contract-testing.md

@@ -0,0 +1,237 @@
+---
+source: options/testing/contract-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# Contract Testing
+
+> **语言**: [English](../../../../options/testing/contract-testing.md) | 简体中文
+
+**上层标准**: [Testing Completeness](../../core/test-completeness-dimensions.md)
+
+---
+
+## 概览
+
+Contract testing 通过测试 consumer 与 provider 之间的协议（contract）来验证服务能否正确通信。它让团队可以独立开发与部署，同时确保彼此兼容。
+
+## 最适用于
+
+- 微服务架构
+- API-first 开发
+- 第三方集成
+- 各自独立工作的团队
+- 分布式系统
+
+## Contract 类型
+
+### Consumer-Driven Contracts (CDC)
+
+由 API consumer 定义的 contract。
+
+**流程：**
+1. Consumer 定义预期的交互
+2. 生成 contract（pact 文件）
+3. Provider 依 contract 进行验证
+4. 部署前双方都必须通过
+
+**好处：**
+- 由 consumer 的需求驱动 API 设计
+- 解耦的部署
+- 提早检测集成问题
+
+### Provider Contracts
+
+由 API provider 定义的 contract。
+
+**使用场景：** 公开 API、OpenAPI-first 设计
+
+**流程：**
+1. Provider 定义 API 规格
+2. Consumer 依规格进行测试
+3. Provider 确保向后兼容性
+
+## 工具
+
+| 工具 | 类型 | 语言 |
+|------|------|-----------|
+| **Pact** | Consumer-driven | 多语言 |
+| **Spring Cloud Contract** | 两者皆可 | JVM |
+| **Dredd** | OpenAPI | 多语言 |
+| **Prism** | Mock | 多语言 |
+
+## Pact 工作流程
+
+### Consumer 端
+
+**1. 定义交互**
+
+```javascript
+const interaction = {
+  state: 'user exists',
+  uponReceiving: 'a request for user by id',
+  withRequest: {
+    method: 'GET',
+    path: '/users/1',
+    headers: { Accept: 'application/json' }
+  },
+  willRespondWith: {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+    body: {
+      id: like(1),
+      name: like('John'),
+      email: like('john@example.com')
+    }
+  }
+};
+```
+
+**2. 执行 consumer 测试** - 测试针对 mock provider 执行
+
+**3. 发布 contract** - 将 pact 文件上传至 broker
+
+### Provider 端
+
+**1. 获取 contract** - 从 broker 下载 contract
+
+**2. 验证 contract**
+
+```javascript
+verifier.verifyProvider({
+  provider: 'UserService',
+  pactBrokerUrl: 'https://broker.example.com',
+  publishVerificationResult: true
+});
+```
+
+**3. State 设置** - 为每个交互设置 provider state
+
+## Pact Broker
+
+contract 的集中式存储库，具备以下功能：
+
+- Contract 存储
+- 验证状态
+- 依赖关系图
+- Can-I-Deploy 检查
+- 供 CI/CD 使用的 Webhook
+
+### Can-I-Deploy
+
+检查部署是否安全：
+
+```bash
+pact-broker can-i-deploy \
+  --pacticipant UserService \
+  --version $(git rev-parse HEAD) \
+  --to production
+```
+
+## CI 集成
+
+### Consumer Pipeline
+
+```yaml
+stages:
+  - test:
+      - Run unit tests
+      - Run contract tests (generates pact)
+  - publish:
+      - Publish pact to broker
+  - can-i-deploy:
+      - Check deployment safety
+  - deploy:
+      - Deploy consumer
+```
+
+### Provider Pipeline
+
+```yaml
+stages:
+  - test:
+      - Run unit tests
+      - Verify consumer contracts
+  - publish:
+      - Publish verification results
+  - can-i-deploy:
+      - Check deployment safety
+  - deploy:
+      - Deploy provider
+```
+
+### GitHub Actions 示例
+
+```yaml
+name: Consumer Contract Tests
+on: [push, pull_request]
+jobs:
+  contract-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run contract tests
+        run: npm run test:contract
+      - name: Publish pact
+        run: npm run pact:publish
+      - name: Can I deploy?
+        run: |
+          pact-broker can-i-deploy \
+            --pacticipant MyConsumer \
+            --version ${{ github.sha }}
+```
+
+## 规则
+
+| 规则 | 说明 | 优先级 |
+|------|-------------|----------|
+| Consumer 优先 | 从 consumer 需求出发，而非 provider 实现 | 建议 |
+| 使用 matcher | 使用类型 matcher（like、eachLike）而非精确值 | 必需 |
+| Provider state | 为每个交互定义清晰的 provider state | 必需 |
+| 为 contract 加版本 | 以 consumer 版本与分支为 contract 加上标签 | 必需 |
+| Can-I-Deploy | 一律在 CI/CD 中执行 can-i-deploy 检查 | 必需 |
+| 破坏性变更 | 进行破坏性变更前先与 consumer 团队协调 | 必需 |
+| 异步 contract | 为异步通信纳入 message contract | 建议 |
+
+## 快速参考
+
+### 工作流程
+
+| 步骤 | Consumer | Provider |
+|------|----------|----------|
+| 1. 定义 | 编写预期 | 实现 API |
+| 2. 测试 | 针对 mock 执行 | 验证 contract |
+| 3. 发布 | 上传 pact | 上传结果 |
+| 4. 部署 | Can-I-Deploy | Can-I-Deploy |
+
+### 好处
+
+| 好处 | 说明 |
+|---------|-------------|
+| 快速反馈 | 不需要完整的集成环境 |
+| 解耦 | 团队可以独立工作 |
+| 安全部署 | Can-I-Deploy 防止破坏性变更 |
+| 活文档 | Contract 记录了 API 行为 |
+
+## 相关选项
+
+- [Integration Testing](./integration-testing.md) - 组件集成测试
+- [E2E Testing](./e2e-testing.md) - 端到端测试
+
+---
+
+## 参考资料
+
+- [Pact Foundation](https://docs.pact.io/)
+- [Martin Fowler - Contract Test](https://martinfowler.com/bliki/ContractTest.html)
+- [Consumer-Driven Contracts](https://martinfowler.com/articles/consumerDrivenContracts.html)
+
+---
+
+## 授权
+
+本文档以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。
+
+**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/options/testing/industry-pyramid.md

@@ -0,0 +1,200 @@
+---
+source: options/testing/industry-pyramid.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+# 业界测试金字塔
+
+> **语言**: [English](../../../../options/testing/industry-pyramid.md) | 简体中文
+
+**上层标准**: [测试完整性](../../core/test-completeness-dimensions.md)
+
+---
+
+## 概览
+
+业界测试金字塔是一套务实的 4 层测试模型，广为敏捷与 DevOps 团队采用。它强调通过大量的 unit test 取得快速反馈、适量的 integration test、用于子系统验证的 system test，以及最少量的端到端测试。
+
+## 最适用于
+
+- 敏捷／Scrum 开发团队
+- 以 CI/CD 为核心的环境
+- 中小型项目
+- DevOps 实践
+- 快速迭代循环
+
+## 金字塔
+
+```
+    ┌─────────┐
+    │   E2E   │  ←  3% (Slow, expensive)
+    ├─────────┤
+    │   ST    │  ←  7% (Medium speed)
+    ├─────────┤
+    │   IT    │  ← 20% (Fast)
+    ├─────────┤
+    │   UT    │  ← 70% (Very fast, many)
+    └─────────┘
+```
+
+**目标比例：** 70/20/7/3（UT/IT/ST/E2E）
+
+**注意：** 此为 Mike Cohn 的经验性建议，并非强制标准。
+
+**理由：**
+- 较多 unit test = 更快的反馈
+- 较少 E2E test = 较低的维护成本
+- integration test 能捕捉接口问题
+- system test 在 stub 外部依赖的情况下验证子系统行为
+
+## 测试层级
+
+### 单元测试（UT）- 70%
+
+| 方面 | 细节 |
+|--------|---------|
+| **定义** | 针对单个函数、方法或类的隔离测试 |
+| **范围** | 单一函数／方法／类 |
+| **速度** | 每个测试 < 100ms |
+| **依赖** | 全部 mock |
+
+**特性：**
+- 执行快速
+- 结果具确定性
+- 无 I/O 操作
+- 测试单一行为单元
+
+### 集成测试（IT）- 20%
+
+| 方面 | 细节 |
+|--------|---------|
+| **定义** | 针对组件交互与数据流的测试 |
+| **范围** | 多个组件相互作用 |
+| **速度** | 每个测试 < 1 秒 |
+| **依赖** | 真实与 mock 混合 |
+
+**特性：**
+- 测试真实的集成
+- 可能使用容器（Testcontainers）
+- 验证数据流
+
+### 系统测试（ST）- 7%
+
+| 方面 | 细节 |
+|--------|---------|
+| **定义** | 在 stub 外部依赖的情况下测试完整子系统 |
+| **范围** | 完整子系统验证 |
+| **速度** | 每个测试 < 10 秒 |
+| **依赖** | 真实内部服务、stub 外部 API |
+
+**特性：**
+- 端到端验证子系统行为
+- stub 外部依赖
+- 在 SIT 环境中测试
+
+### 端到端测试（E2E）- 3%
+
+| 方面 | 细节 |
+|--------|---------|
+| **定义** | 跨整个系统测试完整用户工作流程 |
+| **范围** | 从用户视角的完整用户流程 |
+| **速度** | 每个测试 30 秒至数分钟 |
+| **依赖** | 全部真实 |
+
+**特性：**
+- 模拟真实用户行为
+- 仅测试关键路径
+- 最高的维护成本
+
+## 覆盖率目标
+
+| 指标 | 最低 | 建议 |
+|--------|---------|-------------|
+| 行覆盖率（Line Coverage） | 70% | 85% |
+| 分支覆盖率（Branch Coverage） | 60% | 80% |
+| 函数覆盖率（Function Coverage） | 80% | 90% |
+
+## 各层级工具
+
+### 单元测试
+
+| 语言 | 工具 |
+|----------|-------|
+| JavaScript | Jest, Vitest, Mocha |
+| Python | pytest, unittest |
+| Java | JUnit, TestNG |
+| C# | xUnit, NUnit, MSTest |
+| Go | testing package, testify |
+
+### 集成测试
+
+| 语言 | 工具 |
+|----------|-------|
+| JavaScript | Supertest, Testcontainers |
+| Python | pytest, Testcontainers |
+| Java | Spring Boot Test, Testcontainers |
+| C# | WebApplicationFactory, Testcontainers |
+
+### E2E 测试
+
+| 语言 | 工具 |
+|----------|-------|
+| JavaScript | Playwright, Cypress, Puppeteer |
+| Python | Playwright, Selenium |
+| Java | Selenium, Playwright |
+
+## 何时选择业界金字塔
+
+**选择时机：**
+- 实践敏捷／Scrum 方法论
+- CI/CD 管线至关重要
+- 快速反馈为优先
+- 团队规模小且跨职能
+- 期望最少的文档负担
+
+**避免时机：**
+- 需要正式 QA 认证
+- 企业合规需求
+- 专职 QA 团队偏好 ISTQB
+- 需要审计文档
+
+## 与 ISTQB 的比较
+
+| 业界层级 | ISTQB 对应 | 注意 |
+|----------------|------------------|------|
+| 单元测试（UT） | Component Testing | 概念相同 |
+| 集成测试（IT） | Integration Testing | 概念相同 |
+| 系统测试（ST） | System Testing | 概念相同 |
+| E2E 测试 | Acceptance Testing | 业界 E2E ≈ ISTQB Acceptance |
+
+## 规则
+
+| 规则 | 描述 | 优先级 |
+|------|-------------|----------|
+| 遵循金字塔比例 | UT/IT/ST/E2E 目标 70/20/7/3 比例（经验性，非强制） | Required |
+| 在最低层级测试 | 在能提供信心的最低层级编写测试 | Recommended |
+| 边界情况避免用 E2E | 边界情况使用 unit test，而非 E2E | Recommended |
+| 边界用集成测试 | 使用 integration test 验证接口契约 | Recommended |
+
+## 相关选项
+
+- [ISTQB 框架](./istqb-framework.md) - 正式的 4 层测试框架
+- [单元测试](./unit-testing.md) - 详细的单元测试实践
+- [集成测试](./integration-testing.md) - 集成测试实践
+- [E2E 测试](./e2e-testing.md) - 端到端测试实践
+
+---
+
+## 参考资料
+
+- [Martin Fowler's Testing Pyramid](https://martinfowler.com/bliki/TestPyramid.html)
+- [Google Testing Blog](https://testing.googleblog.com)
+
+---
+
+## 许可
+
+本文档以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。
+
+**来源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)