Use Cases

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Scenario Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendix

Introduction

This document is intended for business analysts and technical architects, systematically explaining the applicability and implementation approaches of the Sparrow microservice framework in various typical business scenarios. Combining the framework's event bus, task scheduling, repository abstraction, projectors, session management, Saga transaction orchestration, and WebSocket real-time communication capabilities, it provides architectural design solutions, implementation steps, and best practices for e-commerce transactions, financial risk control, logistics tracking, content management, real-time communication, and other scenarios. It also provides observability and operational points to help achieve stable implementation in projects of different scales.

Project Structure

Sparrow adopts clean architecture layering and modular organization, with core modules including:

• Bootstrap and Container: Application lifecycle, HTTP routing, event bus Hub, task scheduler wrapper
• Configuration Center: Unified loading and default value settings, covering database, cache, messaging middleware, logging, etc.
• Domain Models: Aggregate root interfaces and event sourcing basic capabilities
• Use Case Layer: Session service, Saga transaction orchestration, task scheduling interfaces and state machines
• Data Persistence: Generic repository implementations (SQL, in-memory, Redis, MongoDB, Badger, etc. adapters)
• Projection and Event Reading: Full projectors, indexers, event readers
• Interface Adapters: HTTP health checks, WebSocket middleware and broadcasting
• Message Bus: JetStream Hub, subscribers, event publish/subscribe

• Application Bootstrap and Lifecycle
  • Provides HTTP service startup, graceful shutdown, subprocess retry and exponential backoff, event Hub registration and cleanup
  • Provides NATS connection resolution, JetStream publish/subscribe encapsulation
• Configuration Center
  • Unified loading of app, server, log, nats, sql, redis, badger, rabbitmq, kafka, casbin, etc. configurations
  • Provides default values, facilitating local development and containerized deployment
• Domain and Event Sourcing
  • Aggregate root interface defines version control, command handling, event application, uncommitted event management, snapshot loading
• Use Case Layer
  • Session Service: Create, get, save, delete, update data, clean expired sessions
  • Saga Transaction Orchestration: Register handlers and compensators, sequential execution, rollback on failure
  • Task Scheduling Interface: Task status, scheduling type, execution mode, concurrent/sequential strategies
• Data Persistence
  • Generic Repository Implementation (SQL): Transaction encapsulation, soft delete, pagination, conditional queries, batch operations
• Projection and Event Reading
  • Full Projector: Rebuild entity views by aggregate type and event collection
• Interface Adapters
  • Health Check: Ready/health check endpoints
  • WebSocket: Upgrade, broadcast, send by user/client, heartbeat keepalive

Sparrow's microservice architecture centers on "Event-Driven + CQRS + Task Orchestration", combined with multi-datasource and message bus, supporting high concurrency and complex business processes.

Scenario 1: E-commerce Platform (High-concurrency Orders and Payments)

• Key Challenges
  • High-concurrency order writes, idempotency, and consistency
  • Distributed transactions for payments, inventory, and coupons
  • Real-time order status and inventory view synchronization
• Framework Capabilities and Implementation
  • Event Sourcing and Aggregate Roots: Order aggregate root receives order placement command, generates order placed event, applies to aggregate state; uncommitted events persisted in transaction then published
  • Session Service: Temporary shopping cart and order token management, automatic cleanup on expiration
  • Saga Transaction Orchestration: Payment, inventory deduction, coupon issuance, notification, etc. steps executed sequentially, automatic compensation on failure
  • Task Scheduling: Timed cleanup of expired orders, asynchronous notification sending, batch settlement
  • Projector: Rebuild order views and inventory indexes from event streams for query side reading
  • Message Bus: Order events published to NATS/JetStream, downstream services subscribe and consume
• Implementation Steps
  1. Define order aggregate root and commands/events, implement event application and snapshot loading
  2. Register session service and cleanup strategy
  3. Orchestrate Saga steps and compensators
  4. Start projector, build order/inventory indexes
  5. Configure NATS/JetStream event publish/subscribe
  6. Deploy task scheduler, configure scheduled tasks
• Performance and Reliability
  • Read-write separation: Event store and view store separated
  • Rate limiting and circuit breaking: Configured at API layer and message consumption side
  • Exponential backoff retry: Subprocess retry during application startup phase ensures reliability

• Key Challenges

  • Transaction consistency and strong consistency read/write
  • Real-time risk control rule matching and alerting
  • Eventual consistency for cross-service transfers and reconciliation

• Framework Capabilities and Implementation

  • Aggregate Roots and Event Sourcing: Account, transaction, risk control rule changes all recorded as events
  • Saga Transactions: Transfer (freeze/debit/credit/unfreeze), reconciliation (difference comparison/supplementary order/compensation)
  • Task Scheduling: Scheduled reconciliation, risk control rule refresh, abnormal transaction retry
  • Event Bus: Transaction events and risk control events decoupled, supporting multi-path subscriptions

• Implementation Steps

  1. Design account and transaction aggregate roots, define commands/events
  2. Orchestrate transfer Saga, register compensation flow
  3. Build risk control rule projection, subscribe to transaction events
  4. Configure reconciliation tasks and exception handling
  5. Deploy event bus, monitoring and alerting

• Performance and Reliability

  • Event store uses high-performance database, view store uses Redis
  • Task scheduler supports concurrent/sequential modes, meeting throughput and ordering requirements

• Key Challenges

  • Multi-stage status transitions (pickup, transfer, delivery, signed)
  • Real-time tracking and exception alerts
  • Cross-system data consistency

• Framework Capabilities and Implementation

  • Aggregate Roots: Package aggregate root records status transition events
  • Projector: Rebuild tracking views by package aggregate type
  • Event Bus: Each node system subscribes to package events, updates own state
  • WebSocket: Real-time push of tracking and exception alerts

• Implementation Steps

  1. Define package aggregate and events
  2. Start projector, build tracking index
  3. Subscribe to events, integrate node systems
  4. Deploy WebSocket, provide frontend real-time push

• Performance and Reliability

  • Event stream retention policy and compression configuration
  • Event replay and snapshots accelerate rebuilding

• Key Challenges

  • Content versioning and permission control
  • Multimedia content distribution and caching

• Framework Capabilities and Implementation

  • Session Service: Login state and permission token management
  • Event Bus: Content change event-driven distribution
  • Configuration Center: Casbin permission model and policy files

• Implementation Steps

  1. Integrate Casbin permission model
  2. Content change event publish and subscribe
  3. Session service and JWT integration

• Performance and Reliability

  • Cache layer (Redis) and event store separated
  • Event replay and snapshots improve rebuilding efficiency

• Key Challenges

  • High-concurrency connections and message broadcasting
  • Heartbeat keepalive and abnormal disconnection handling

• Framework Capabilities and Implementation

  • WebSocket Middleware: Connection upgrade, heartbeat, broadcast, send by user/client
  • Event Bus: Works with business events for system-level notifications

• Implementation Steps

  1. Introduce WebSocket middleware
  2. Implement broadcast and user-specific push
  3. Configure heartbeat interval and disconnection cleanup

• Performance and Reliability

  • Connection pool and read-write separation
  • Automatic removal of invalid connections on heartbeat failure

• External Dependencies
  • Web Framework: Gin
  • Logging: Zap
  • Messaging: NATS, RabbitMQ, Kafka
  • Caching: Redis
  • Databases: PostgreSQL, SQLite, MongoDB
  • Permissions: Casbin
• Internal Module Coupling
  • App depends on configuration, logging, container, task scheduling, message bus
  • Use case layer depends on repository abstraction and domain events
  • Projector depends on event reading and indexer
  • Interface adapters depend on use case layer and message bus

• Event Store and View Separation: Event store for auditing and replay, view store for high read performance
• Task Scheduling Concurrency and Sequencing: Choose concurrent or sequential execution based on business characteristics, reasonably set maximum concurrency
• Event Bus Retention Policy: Set event retention days based on compliance and cost balance
• Session TTL: Reasonably set session expiration time to reduce invalid data occupation
• Database Transactions: Repository implementation has built-in transaction encapsulation, note performance impact of batch operations and soft delete
• WebSocket: Heartbeat interval and connection pool size need tuning based on concurrent connection count

[This section provides general guidance, does not directly analyze specific files]

Troubleshooting Guide

• Application Startup Failure
  • Check if configuration items are correctly loaded and default values are reasonable
  • Observe subprocess retry logs during application startup phase, locate dependency service unavailability issues
• Events Not Being Consumed
  • Check NATS/JetStream connection and stream configuration
  • Verify event subscriber registration and handler implementation
• Tasks Not Executing or Backlogged
  • Check task scheduler status and execution mode
  • Focus on task retry and dead letter queue
• Session Anomalies
  • Check session expiration and cleanup logic
  • Confirm repository save and query paths
• WebSocket Disconnections
  • Check heartbeat interval and network proxy
  • Focus on connection pool cleanup and abnormal disconnection handling

Sparrow framework provides highly extensible, highly reliable, observable microservice infrastructure for e-commerce, finance, logistics, content, and real-time communication scenarios through event sourcing, CQRS, task orchestration, and message bus. Combined with configuration center, generic repositories, and projectors, it can be quickly implemented in projects of different scales and continuously evolve.

[This section is summary content, does not directly analyze specific files]

Appendix

• Health Check Endpoints
  • Ready check and health check interfaces, facilitating container orchestration and platform integration
• Task Routing (Reserved)
  • Task-related routing and handler placeholders, facilitating future extensions