AgentSkillsCN

Event Style Guide

事件驱动设计规范：事件封装格式、命名规则、版本管理策略、Schema 迭代准则、幂等性要求、事件排序与分区机制，以及重试与死信处理方案

SKILL.md
--- frontmatter
name: Event Style Guide
description: Event-driven design conventions: event envelope, naming, versioning, schema evolution rules, idempotency, ordering/partitioning, retry and dead-letter handling

Event Style Guide

Overview

มาตรฐานการออกแบบ events สำหรับ event-driven architecture: envelope format, naming, versioning, และ schema evolution ที่ทำให้ระบบ decouple ได้อย่างปลอดภัย

Why This Matters

  • •Interoperability: ทุก service เข้าใจ event format เดียวกัน
  • •Evolution: เปลี่ยน schema โดยไม่ break consumers
  • •Debugging: Trace events ข้าม services ได้
  • •Contract: Clear agreement between producers/consumers

Core Concepts

1. Event Envelope Structure

  • •ทุก event ต้องเป็น envelope เดียวกัน เพื่อให้ tooling/observability ทำงานได้
  • •metadata ต้องมี id, type, source, time, specVersion
  • •correlation ต้องมี correlationId (ผูกกับ request/trace) และ causationId (optional)
  • •payload อยู่ใน data เท่านั้น (หลีกเลี่ยง “metadata ปน payload”)

2. Event Naming Convention

  • •รูปแบบ: <domain>.<entity>.<action>.v<major>
  • •ใช้ past-tense สำหรับ domain events (created, updated, completed)
  • •actions ต้องสื่อความหมายและไม่กว้างเกินไป (หลีกเลี่ยง changed, processed ถ้าไม่จำเป็น)

3. Event Versioning

  • •version ใน type เป็น major เพื่อบอก breaking changes: user.created.v1
  • •changes แบบ non-breaking (เพิ่ม field optional) ไม่ต้อง bump major แต่ควร track schema version ใน registry
  • •หากต้อง breaking: ออก v2 และรองรับ consumers เก่าในช่วง deprecation

4. Schema Evolution

กฎหลัก: consumers ต้อง “ignore unknown fields” และ producers ต้องไม่ลบ/เปลี่ยนความหมาย field เดิมภายใน major เดียวกัน

  • •✅ เพิ่ม field optional (หรือเพิ่ม enum values แบบ backward-compatible ถ้า consumers handle unknown)
  • •❌ ลบ field, rename field, เปลี่ยน type, เพิ่ม required field
  • •ถ้าจำเป็นต้อง rename: ทำแบบ “add new + deprecate old” แล้วค่อยตัดใน major ถัดไป

5. Event Types

  • •Domain events: facts ที่เกิดขึ้นแล้ว (source-of-truth) เช่น order.payment.completed.v1
  • •Integration events: แปล domain event สำหรับระบบอื่น/ภายนอก (อาจ mask/redact fields)
  • •Commands: “ขอให้ทำ” (ควรเป็น request/response หรือ separate channel) ไม่ควรปนกับ domain events

6. Idempotency

  • •id ต้อง unique (UUID v4) และใช้สำหรับ dedupe ที่ consumer
  • •consumer ต้อง idempotent: บันทึก eventId ที่ process แล้ว หรือใช้ upsert/deterministic state transitions
  • •ถ้า broker อาจส่งซ้ำ (at-least-once) ให้คาดไว้ตั้งแต่แรก

7. Event Ordering

  • •ถ้าต้องการ ordering ให้ define partition key (เช่น tenantId, orderId) และส่งไป partition เดียวกัน
  • •ถ้าต้อง strict ordering ต่อ entity ให้มี sequence (optional) ใน data หรือ details
  • •หลีกเลี่ยงการพึ่ง ordering ข้าม partition (แทบไม่รับประกัน)

8. Dead Letter Handling

  • •define retry policy: exponential backoff + jitter + max attempts
  • •classify errors: retryable vs non-retryable (validation/domain errors ไม่ควร retry)
  • •เมื่อเกิน max retries ให้ส่ง DLQ พร้อม metadata ที่พอสำหรับ replay (แต่ไม่ใส่ secrets/PII เกินจำเป็น)
  • •ต้องมี playbook: “inspect → fix → replay”

Quick Start

typescript
export interface EventEnvelope<T> {
  id: string;
  type: string;
  source: string;
  specVersion: "1.0";
  time: string;

  correlationId: string;
  causationId?: string;

  dataContentType: "application/json";
  dataSchema?: string;
  data: T;
}

export type UserCreatedV1 = EventEnvelope<{
  userId: string;
  email: string;
  tenantId: string;
}>;

Production Checklist

  • • All events follow envelope standard
  • • Event naming consistent
  • • Version in every event
  • • Schema registered in registry
  • • Idempotency keys present
  • • Dead letter queue configured

Event Envelope Standard

typescript
interface EventEnvelope<T> {
  // Metadata
  id: string;                    // UUID v4
  type: string;                  // "user.created.v1"
  source: string;                // "user-service"
  specVersion: string;           // "1.0"
  time: string;                  // ISO 8601

  // Correlation
  correlationId: string;         // Request correlation
  causationId?: string;          // Causing event ID

  // Payload
  data: T;                       // Event-specific data
  dataContentType: string;       // "application/json"
  dataSchema?: string;           // Schema URL
}

Retry & DLQ Policy (ตัวอย่าง)

  • •retry: 1s, 5s, 15s, 1m, 5m (max 5 ครั้ง) + jitter
  • •non-retryable: VAL_, BIZ_, AUTH_, AUTHZ_ (ส่ง DLQ ทันทีหรือ discard ตาม policy)
  • •DLQ message ต้องมี: original event.id, event.type, error summary, attempt count, first/last seen timestamp

Event Naming Convention

code
# Format: <domain>.<entity>.<action>.v<version>

# Examples:
user.account.created.v1
order.payment.completed.v1
inventory.stock.reserved.v1
notification.email.sent.v1

# Actions (past tense for domain events):
- created, updated, deleted
- completed, failed, cancelled
- started, finished, expired

Schema Evolution Rules

Change TypeCompatibilityExample
Add optional field✅ SafeAdd middleName?: string
Add required field❌ BreakingAdd email: string
Remove field❌ BreakingRemove age
Rename field❌ Breakingname → fullName
Change type❌ Breakingage: string → age: number

Anti-patterns

  1. •No versioning: Can't evolve schemas
  2. •Massive payloads: Events too large
  3. •Missing correlation: Can't trace flows
  4. •Shared events: Tight coupling between services
  5. •Hidden contracts: schema อยู่ใน code แต่ไม่มี registry/docs

Integration Points

  • •Message brokers (Kafka, RabbitMQ)
  • •Schema registries
  • •Event stores
  • •Monitoring systems

Further Reading