事件契约生成器

技能文档

---
name: amnadtaowsoam-event-contract-generator
title: 事件契约生成器
description: "自动生成事件契约（JSON Schema、TypeScript 类型、校验器），确保事件驱动架构中生产者和消费者使用统一的事件格式，保障类型安全与数据校验。触发词：事件契约、事件 Schema、事件类型生成、事件校验器、事件驱动、JSON Schema。"
category: 开发工具
---

# 事件契约生成器

## 技能简介

自动生成事件契约（Schema、类型、校验器），确保生产者和消费者使用统一的事件格式。保障事件驱动架构中的类型安全与数据校验。

## 技能定位
*（至少选择一个定位以启用特定模块）*
- [ ] **运维**
- [x] **后端**
- [ ] **前端**
- [ ] **AI-RAG**
- [ ] **安全关键**

## 概述

自动生成事件契约（Schema、类型、校验器），确保生产者和消费者使用统一的事件格式。保障事件驱动架构中的类型安全与数据校验。

## 为什么需要这个

- **类型安全**：从 Schema 生成 TypeScript 类型
- **数据校验**：自动校验事件格式
- **文档生成**：自动生成事件目录文档
- **版本管理**：追踪 Schema 变更

---

## 核心概念与规则

### 1. 核心原则
- 遵循已建立的模式和约定
- 保持代码库的一致性
- 记录决策和权衡

### 2. 实施指南
- 从最简可行方案开始
- 根据反馈和需求迭代
- 部署前充分测试


## 输入 / 输出 / 契约

* **输入**：
  - 事件名称（如 `user.created`）
  - 事件数据结构
  - 版本号（可选，默认为 1.0.0）
  - 生产者/消费者信息
* **前置条件**：
  - 已采用事件驱动架构
  - 已配置事件总线/消息系统
* **输出**：
  - JSON Schema 文件
  - TypeScript 类型文件
  - 校验函数
  - 示例事件
  - 事件目录文档
* **交付物**：
  - 事件 Schema（JSON Schema）
  - TypeScript 类型
  - 校验函数
  - 事件目录条目
  - 示例事件
* **验收证据**：
  - Schema 校验通过
  - TypeScript 类型编译通过
  - 校验器按预期工作
  - 文档完整
* **成功标准**：
  - Schema 为有效的 JSON Schema
  - 类型与 Schema 匹配
  - 校验器能捕获无效事件
  - 文档清晰

## 技能组合
* **依赖**：无
* **兼容**：其他后端服务类技能
* **冲突**：无

---

## 快速开始 / 实施示例

1. 审查需求和约束
2. 搭建开发环境
3. 按照模式实现核心功能
4. 为关键路径编写测试
5. 运行测试并修复问题
6. 记录任何偏差或决策

```python
# 遵循最佳实践的示例实现
def example_function():
    # 在此编写实现
    pass
```


## 假设 / 约束 / 非目标

* **假设**：
  - 开发环境已正确配置
  - 所需依赖可用
  - 团队具备基本的领域理解
* **约束**：
  - 必须遵循现有代码库约定
  - 时间和资源限制
  - 兼容性要求
* **非目标**：
  - 本技能不覆盖范围外的边界情况
  - 不替代正式培训


## 兼容性与前置条件

* **支持版本**：
  - Python 3.8+
  - Node.js 16+
  - 现代浏览器（Chrome、Firefox、Safari、Edge）
* **所需工具**：
  - 代码编辑器（推荐 VS Code）
  - 对应语言的测试框架
  - 版本控制（Git）
* **依赖**：
  - 语言特定的包管理器
  - 构建工具
  - 测试库
* **环境配置**：
  - `.env.example` 键：`API_KEY`、`DATABASE_URL`（不含值）


## 测试场景矩阵（QA 策略）

| 类型 | 关注领域 | 所需场景 / Mock |
| :--- | :--- | :--- |
| **单元测试** | 核心逻辑 | 须覆盖主要逻辑和至少 3 个边界/错误场景，目标最低 80% 覆盖率 |
| **集成测试** | 数据库 / API | 单元测试期间须 Mock 所有外部 API 调用或数据库连接 |
| **端到端测试** | 用户旅程 | 需测试的关键用户流程 |
| **性能测试** | 延迟 / 负载 | 基准测试要求 |
| **安全测试** | 漏洞 / 认证 | SAST/DAST 或依赖审计 |
| **前端测试** | 用户体验 / 无障碍 | 无障碍检查清单（WCAG）、性能预算（Lighthouse 分数） |


## 技术护栏与安全威胁模型

### 1. 安全与隐私（威胁模型）
* **主要威胁**：注入攻击、认证绕过、数据泄露
- [ ] **数据处理**：清理所有用户输入以防止注入攻击，禁止记录原始 PII
- [ ] **密钥管理**：禁止硬编码 API 密钥，使用环境变量/密钥管理器
- [ ] **授权**：状态变更前验证用户权限

### 2. 性能与资源
- [ ] **执行效率**：考虑算法的时间复杂度
- [ ] **内存管理**：对大数据集使用流/分页
- [ ] **资源清理**：在 finally 块中关闭数据库连接/文件句柄

### 3. 架构与可扩展性
- [ ] **设计模式**：遵循 SOLID 原则，使用依赖注入
- [ ] **模块化**：将逻辑与 UI/框架解耦

### 4. 可观测性与可靠性
- [ ] **日志规范**：结构化 JSON，包含追踪 ID `request_id`
- [ ] **指标**：追踪 `error_rate`、`latency`、`queue_depth`
- [ ] **错误处理**：标准化错误码，禁止裸 except
- [ ] **可观测性产物**：
    - **日志字段**：timestamp、level、message、request_id
    - **指标**：request_count、error_count、response_time
    - **仪表盘/告警**：高错误率 > 5%


## Agent 指令与错误恢复

- **思考过程**：修复前先分析根因，禁止暴力尝试
- **回退策略**：测试失败 3 次后停止，输出根因并请求人工介入/澄清
- **自我审查**：最终确定前对照护栏和反模式检查
- **输出约束**：仅输出修改后的代码块，除非被要求否则不解释


## 完成定义（DoD）检查清单

- [ ] 测试通过 + 覆盖率达标
- [ ] Lint/类型检查通过
- [ ] 日志/指标/追踪已实现
- [ ] 安全检查通过
- [ ] 文档/变更日志已更新
- [ ] 无障碍/性能要求达标（如涉及前端）


## 反模式 / 陷阱

* **禁止**：记录 PII、捕获所有异常、N+1 查询
* **注意**：常见症状和快速修复
* **建议**：使用正确的错误处理、分页和日志


## 参考链接与示例

* 内部文档和示例
* 官方文档和最佳实践
* 社区资源和讨论


## 版本与变更日志

* **版本**：1.0.0
* **变更日志**：
  - 2026-02-22：初始版本，完整模板结构

使用说明

# 事件契约生成器

自动生成事件契约（JSON Schema、TypeScript 类型、校验器），确保事件驱动架构中生产者和消费者使用统一的事件格式。

## 功能概述

本技能为事件驱动架构提供完整的事件契约生成能力，包括：

- **JSON Schema 生成**：根据事件定义生成标准 Schema
- **TypeScript 类型**：从 Schema 自动推导类型定义
- **校验函数**：生成运行时事件校验逻辑
- **事件目录**：自动维护事件文档
- **版本管理**：追踪 Schema 演进

## 使用方法

1. 提供事件名称（如 `user.created`）和数据结构
2. 指定版本号（可选，默认 1.0.0）
3. 提供生产者/消费者信息
4. 获得完整的契约交付物：Schema、类型、校验器、示例和文档

## 前置条件

- 已采用事件驱动架构
- 已配置事件总线或消息系统
- Python 3.8+ 或 Node.js 16+

## 交付物

- 事件 Schema（JSON Schema 格式）
- TypeScript 类型定义
- 校验函数
- 事件目录文档条目
- 示例事件数据

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。