API 契约审计员 - 自动化审计 API 契约、服务边界与 DTO 模式的开发者工具

ln-643-api-contract-auditor by levnikolaevich/claude-code-skills

195 周安装量

304 GitHub Stars

安装命令

npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-643-api-contract-auditor

🇨🇳中文介绍

路径说明： 文件路径（shared/、references/、../ln-*）是相对于技能仓库根目录的。如果在当前工作目录中未找到，请定位此 SKILL.md 文件所在的目录，然后向上返回一级即为仓库根目录。如果缺少 shared/ 目录，请通过 WebFetch 从 https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path} 获取文件。

API 契约审计员 (L3 工作者)

专门审计 API 契约、服务边界处的方法签名以及 DTO 使用模式的工作者。

目的与范围

ln-640 协调器流水线中的工作者 - 由 ln-640-pattern-evolution-auditor 调用
在架构层面审计 API 契约（服务边界、层分离）
检查层泄漏、DTO 模式、错误契约一致性
返回包含 4 项评分（合规性、完整性、质量、实现）的结构化分析

超出范围（由 ln-623-code-principles-auditor 负责）：

代码重复（相同的 DTO 结构重复、相同的映射逻辑、相同的验证）
仅报告架构边界相关发现（错误的层、缺失的契约）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

输入（来自 ln-640 协调器）

- pattern: "API Contracts"     # 模式名称
- locations: string[]          # 服务/API 目录
- adr_reference: string        # 相关 ADR 的路径
- bestPractices: object        # 来自 MCP Ref/Context7 的最佳实践
- output_dir: string           # 例如："docs/project/.audit/ln-640/{YYYY-MM-DD}"

# 领域感知（可选，来自协调器）
- domain_mode: "global" | "domain-aware"   # 默认："global"
- current_domain: string                   # 例如："users", "billing"（仅在领域感知模式下）
- scan_path: string                        # 例如："src/users/"（仅在领域感知模式下）

阶段 0：加载参考文件

必须阅读： 加载 shared/references/two_layer_detection.md 以了解检测方法。加载 references/detection_patterns.md - 所有 5 条规则的语言特定 Grep 模式。

阶段 1：发现服务边界

scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root

1. 查找 API 层：Glob("**/api/**/*.py", "**/routes/**/*.ts", "**/controllers/**/*.ts", root=scan_root)
2. 查找服务层：Glob("**/services/**/*.py", "**/services/**/*.ts", root=scan_root)
3. 查找领域层：Glob("**/domain/**/*.py", "**/models/**/*.py", root=scan_root)
4. 映射：哪些 API 端点调用了哪些服务

阶段 2：分析契约（5 条规则）

必须阅读： 使用 detection_patterns.md 中每条规则的语言特定 Grep 模式。

| 规则 | 严重性 | 检查内容

---|---|---|---
1 | 层泄漏 | 高/中 | 服务/领域层接受 HTTP 类型（Request、parsed_body、headers）
2 | 缺失 DTO | 中/低 | 4+ 个参数在 2+ 个方法中重复出现而未分组为 DTO
3 | 实体泄漏 | 高/中 | API 返回 ORM 实体而未使用响应 DTO。降级情况：无外部消费者的内部 API → 低
4 | 错误契约 | 中/低 | 同一服务中混合使用错误模式（raise + return None）
5 | 冗余重载 | 低/中 | 方法对使用 _with_/_and_ 后缀，仅相差 1-2 个参数
6 | 架构诚实性 | 高/中 | 读取命名函数（get_/find_/check_/validate_/is_/has_）的函数体包含写入副作用。排除项遵循 shared/references/ai_ready_architecture.md

范围边界： 跳过重复性发现（由 ln-623 负责），仅报告架构边界相关发现。

阶段 3：计算 4 项评分

合规性评分 (0-100)：

标准	分值
无层泄漏（服务中无 HTTP 类型）	+35
一致的错误处理模式	+25
遵循项目命名约定	+10
读取命名函数中无隐藏副作用	+10
无实体泄漏到 API	+20

完整性评分 (0-100)：

标准	分值
所有服务方法都有类型化参数	+30
所有服务方法都有类型化返回值	+30
为复杂数据定义了 DTO	+20
错误类型已记录/类型化	+20

质量评分 (0-100)：

标准	分值
服务方法中无非布尔标志参数	+15
无隐藏写入操作的不透明返回类型	+10
无超过 5 个参数且未使用 DTO 的方法	+25
模块内命名一致	+25
无冗余重载	+25

实现评分 (0-100)：

标准	分值
DTO/模式存在且被使用	+30
存在类型注解	+25
边界处有验证（Pydantic、Zod）	+25
API 响应 DTO 与领域层分离	+20

阶段 3.5：计算评分

必须阅读： 加载 shared/references/audit_worker_core_contract.md 和 shared/references/audit_scoring.md。

主要评分 使用惩罚公式（与所有工作者相同）：

penalty = (critical × 2.0) + (high × 1.0) + (medium × 0.5) + (low × 0.2)
score = max(0, 10 - penalty)

诊断子评分（每项 0-100）单独计算，并仅在 AUDIT-META 中报告用于诊断目的。

阶段 4：撰写报告

必须阅读： 加载 shared/references/audit_worker_core_contract.md 和 shared/templates/audit_worker_report_template.md。

# 在内存中构建 Markdown 报告，包含：
# - AUDIT-META（扩展：评分[基于惩罚] + 诊断评分 compliance/completeness/quality/implementation）
# - 检查表（layer_leakage, missing_dto, entity_leakage, error_contracts, redundant_overloads）
# - 发现表（按严重性排序的问题）
# - DATA-EXTENDED：包含 principle + domain 字段的问题数组（用于跨领域聚合）

IF domain_mode == "domain-aware":
  写入到 {output_dir}/643-api-contract-{current_domain}.md
ELSE:
  写入到 {output_dir}/643-api-contract.md

阶段 5：返回摘要

报告已写入：docs/project/.audit/ln-640/{YYYY-MM-DD}/643-api-contract-users.md
评分：6.75/10 (C:65 K:70 Q:55 I:80) | 问题：4 (H:2 M:1 L:1)

必须阅读： 加载 shared/references/audit_worker_core_contract.md。

仅限架构层面： 关注服务边界，而非内部实现
评分前阅读： 切勿在未阅读实际服务代码的情况下评分
范围边界： 跳过重复性发现（由 ln-623 负责）
检测模式： 使用 detection_patterns.md 中的语言特定 Grep
领域感知： 当 domain_mode="domain-aware" 时，仅扫描 scan_path，并为发现标记领域

必须阅读： 加载 shared/references/audit_worker_core_contract.md。

已发现服务边界（API、服务、领域层）
已提取并分析方法签名
已使用 detection_patterns.md 检查所有 5 条规则
已应用范围边界（不与 ln-623 重复）
已计算 4 项评分并附有理由
已识别问题，包含严重性、位置、建议、工作量
如果是领域感知模式：发现已标记 domain 字段
报告已写入 {output_dir}/643-api-contract[-{domain}].md（原子性单次写入调用）
摘要已返回给协调器

检测模式：references/detection_patterns.md
评分规则：../ln-640-pattern-evolution-auditor/references/scoring_rules.md
模式库：../ln-640-pattern-evolution-auditor/references/pattern_library.md

版本： 2.0.0 最后更新： 2026-02-08

🇺🇸English

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

API Contract Auditor (L3 Worker)

Specialized worker auditing API contracts, method signatures at service boundaries, and DTO usage patterns.

Purpose & Scope

Worker in ln-640 coordinator pipeline - invoked by ln-640-pattern-evolution-auditor
Audit API contracts at architecture level (service boundaries, layer separation)
Check layer leakage, DTO patterns, error contract consistency
Return structured analysis with 4 scores (compliance, completeness, quality, implementation)

Out of Scope (owned by ln-623-code-principles-auditor):

Code duplication (same DTO shape repeated, same mapping logic, same validation)
Report only ARCHITECTURE BOUNDARY findings (wrong layer, missing contract)

Input (from ln-640 coordinator)

- pattern: "API Contracts"     # Pattern name
- locations: string[]          # Service/API directories
- adr_reference: string        # Path to related ADR
- bestPractices: object        # Best practices from MCP Ref/Context7
- output_dir: string           # e.g., "docs/project/.audit/ln-640/{YYYY-MM-DD}"

# Domain-aware (optional, from coordinator)
- domain_mode: "global" | "domain-aware"   # Default: "global"
- current_domain: string                   # e.g., "users", "billing" (only if domain-aware)
- scan_path: string                        # e.g., "src/users/" (only if domain-aware)

Workflow

Phase 0: Load References

MANDATORY READ: Load shared/references/two_layer_detection.md for detection methodology. Load references/detection_patterns.md — language-specific Grep patterns for all 5 rules.

Phase 1: Discover Service Boundaries

scan_root = scan_path IF domain_mode == "domain-aware" ELSE codebase_root

1. Find API layer: Glob("**/api/**/*.py", "**/routes/**/*.ts", "**/controllers/**/*.ts", root=scan_root)
2. Find service layer: Glob("**/services/**/*.py", "**/services/**/*.ts", root=scan_root)
3. Find domain layer: Glob("**/domain/**/*.py", "**/models/**/*.py", root=scan_root)
4. Map: which services are called by which API endpoints

Phase 2: Analyze Contracts (5 Rules)

MANDATORY READ: Use detection_patterns.md for language-specific Grep patterns per rule.

| Rule | Severity | What to Check

---|---|---|---
1 | Layer Leakage | HIGH/MEDIUM | Service/domain accepts HTTP types (Request, parsed_body, headers)
2 | Missing DTO | MEDIUM/LOW | 4+ params repeated in 2+ methods without grouping DTO
3 | Entity Leakage | HIGH/MEDIUM | ORM entity returned from API without response DTO. Downgrade when: internal API with no external consumers → LOW
4 | Error Contracts | MEDIUM/LOW | Mixed error patterns (raise + return None) in same service
5 | Redundant Overloads | LOW/MEDIUM | Method pairs with _with_/_and_ suffix differing by 1-2 params
6 | Architectural Honesty | HIGH/MEDIUM | Read-named function (get_/find_/check_/validate_/is_/has_) body contains write side-effects. Exclusions per shared/references/ai_ready_architecture.md

Scope boundary: SKIP DUPLICATION findings (owned by ln-623), REPORT only ARCHITECTURE BOUNDARY findings.

Phase 3: Calculate 4 Scores

Compliance Score (0-100):

Criterion	Points
No layer leakage (HTTP types in service)	+35
Consistent error handling pattern	+25
Follows project naming conventions	+10
No hidden side-effects in read-named functions	+10
No entity leakage to API	+20

Completeness Score (0-100):

Criterion	Points
All service methods have typed params	+30
All service methods have typed returns	+30
DTOs defined for complex data	+20
Error types documented/typed	+20

Quality Score (0-100):

Criterion	Points
No boolean flag params in service methods	+15
No opaque return types hiding write actions	+10
No methods with >5 params without DTO	+25
Consistent naming across module	+25
No redundant overloads	+25

Implementation Score (0-100):

Criterion	Points
DTOs/schemas exist and are used	+30
Type annotations present	+25
Validation at boundaries (Pydantic, Zod)	+25
API response DTOs separate from domain	+20

Phase 3.5: Calculate Score

MANDATORY READ: Load shared/references/audit_worker_core_contract.md and shared/references/audit_scoring.md.

Primary score uses penalty formula (same as all workers):

penalty = (critical × 2.0) + (high × 1.0) + (medium × 0.5) + (low × 0.2)
score = max(0, 10 - penalty)

Diagnostic sub-scores (0-100 each) are calculated separately and reported in AUDIT-META for diagnostic purposes only.

Phase 4: Write Report

MANDATORY READ: Load shared/references/audit_worker_core_contract.md and shared/templates/audit_worker_report_template.md.

# Build markdown report in memory with:
# - AUDIT-META (extended: score [penalty-based] + diagnostic score_compliance/completeness/quality/implementation)
# - Checks table (layer_leakage, missing_dto, entity_leakage, error_contracts, redundant_overloads)
# - Findings table (issues sorted by severity)
# - DATA-EXTENDED: issues array with principle + domain fields (for cross-domain aggregation)

IF domain_mode == "domain-aware":
  Write to {output_dir}/643-api-contract-{current_domain}.md
ELSE:
  Write to {output_dir}/643-api-contract.md

Phase 5: Return Summary

Report written: docs/project/.audit/ln-640/{YYYY-MM-DD}/643-api-contract-users.md
Score: 6.75/10 (C:65 K:70 Q:55 I:80) | Issues: 4 (H:2 M:1 L:1)

Critical Rules

MANDATORY READ: Load shared/references/audit_worker_core_contract.md.

Architecture-level only: Focus on service boundaries, not internal implementation
Read before score: Never score without reading actual service code
Scope boundary: SKIP duplication findings (owned by ln-623)
Detection patterns: Use language-specific Grep from detection_patterns.md
Domain-aware: When domain_mode="domain-aware", scan only scan_path, tag findings with domain

Definition of Done

MANDATORY READ: Load shared/references/audit_worker_core_contract.md.

Service boundaries discovered (API, service, domain layers)
Method signatures extracted and analyzed
All 5 rules checked using detection_patterns.md
Scope boundary applied (no duplication with ln-623)
4 scores calculated with justification
Issues identified with severity, location, suggestion, effort
If domain-aware: findings tagged with domain field
Report written to {output_dir}/643-api-contract[-{domain}].md (atomic single Write call)
Summary returned to coordinator

Reference Files

Detection patterns: references/detection_patterns.md
Scoring rules: ../ln-640-pattern-evolution-auditor/references/scoring_rules.md
Pattern library: ../ln-640-pattern-evolution-auditor/references/pattern_library.md

Version: 2.0.0 Last Updated: 2026-02-08

Weekly Installs

148

Repository

levnikolaevich/…e-skills

GitHub Stars

245

First Seen

Feb 7, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

cursor137

gemini-cli136

github-copilot135

opencode135

codex134

claude-code134

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

36,300 周安装