事件契约生成器

技能文档

---
name: amnadtaowsoam-event-contract-generator
title: 事件契约生成器
description: 为事件驱动架构自动生成事件契约（JSON Schema、TypeScript 类型、校验器），保证生产者与消费者使用同一事件格式，确保类型安全与自动校验。当用户需要定义事件格式、生成事件 Schema、给消息队列/事件总线补充类型与校验时触发。触发词：事件契约、事件 Schema、JSON Schema、TypeScript 类型生成、事件驱动、消息校验。
category: 开发工具
---

# 事件契约生成器

## 概述

为事件驱动架构自动生成事件契约（Schema、类型定义、校验器），使事件的生产方和消费方使用同一份事件格式，保证类型安全与自动校验。

**核心价值**：
- **类型安全**：从 Schema 生成 TypeScript 类型
- **自动校验**：事件自动通过校验器验证
- **文档化**：自动生成事件目录
- **版本管理**：跟踪 Schema 变更

## 技能工作流

### 步骤1：收集事件信息

向用户确认或从代码中提取：
- 事件名称（如 `user.created`）
- 事件数据结构（字段、类型、必填项）
- 版本号（可选，默认 1.0.0）
- 生产者/消费者信息

### 步骤2：生成 JSON Schema

根据事件结构生成符合 JSON Schema 规范的契约文件，包含字段类型、必填约束与描述。

### 步骤3：生成 TypeScript 类型

基于 Schema 生成对应的 TypeScript 类型定义文件，供生产者与消费者共用。

### 步骤4：生成校验器

生成事件校验函数，在消息发送与消费入口处自动校验事件合法性，拦截不合规事件。

### 步骤5：输出示例与事件目录

- 输出示例事件（正常与异常样例）
- 更新事件目录文档，记录事件名称、版本、生产者、消费者与结构说明

### 步骤6：验证交付

- Schema 能通过 JSON Schema 校验器验证
- TypeScript 类型可编译通过
- 校验器能正确拦截非法事件
- 事件目录文档完整清晰

## 输入 / 输出

**输入**：事件名称、事件数据结构、版本号（可选）、生产者/消费者信息。

**输出（交付物）**：
- JSON Schema 文件
- TypeScript 类型文件
- 校验器函数
- 示例事件
- 事件目录条目

**验收标准**：Schema 为合法 JSON Schema；类型与 Schema 一致；校验器可拦截无效事件；文档清晰完整。

## 前置条件

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

## 注意事项

- 遵循既有代码库的命名与目录约定
- Schema 变更需递增版本号，保持向后兼容
- 禁止在日志中输出敏感个人数据（PII）
- 从最简单可行的方案开始，根据反馈迭代

## 常见反模式

- ⛔ 不要在 Schema 中省略必填约束与字段描述
- ⚠️ 注意生产者与消费者版本不一致导致的校验失败
- 💡 正确做法：契约先行，变更走版本化流程

使用说明

# 事件契约生成器

为事件驱动架构自动生成事件契约（JSON Schema、TypeScript 类型、校验器），保证生产者与消费者使用同一事件格式。

## 功能

- 根据事件结构生成 JSON Schema 契约文件
- 从 Schema 生成 TypeScript 类型定义
- 生成事件校验函数，自动拦截非法事件
- 输出示例事件并维护事件目录文档

## 最简用法

向 Agent 描述你的事件结构即可：

```text
为事件 user.created 生成事件契约，字段包括 user_id（string，必填）、
email（string）、created_at（datetime），生产者是用户服务，消费者是邮件服务
```

执行后将得到 Schema 文件、TypeScript 类型、校验器与示例事件。

## 前置条件

- 项目采用事件驱动架构（消息队列 / 事件总线已配置）
- Python 3.8+ 或 Node.js 16+

如何安装此技能？

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