go-kratos/examples

The kratos-realtimemap project is a real-time public transportation map implementation based on Proto.Actor. It demonstrates how to build a microservices-based real-time system using the Kratos framework.

Key Features and Architecture

• Data Ingestion: Uses MQTT to collect open experimental data (based on HFP API or GTFS standards).
• Communication Patterns:
  • Websocket: Used for streaming real-time telemetry/coordinate data to the frontend.
  • RESTful API: Used for relatively static data such as geofences, vehicle attributes, and historical telemetry data.
• BFF Pattern: Utilizes Kratos as a Backend-for-Frontend (BFF) to communicate with the web client.
• Simplified Implementation: For demonstration purposes, this version uses in-memory caching instead of Redis and bypasses Kafka, though a production version would typically pipe MQTT data into Kafka for downstream microservice consumption.

The go-kratos/go-kratos/examples repository contains a collection of practical implementations demonstrating various Kratos features and patterns. You can use these examples to understand how to implement specific functionalities in your own Kratos-based microservices.

Key categories of examples include:

Security & Authentication

• JWT: Using JSON Web Tokens for authentication (auth/jwt).
• Casbin: Combining JWT authentication with Casbin-based authorization (casbin).
• TLS: Implementing TLS certificate usage (tls).

Communication & Protocols

• RPC: Basic Remote Procedure Call examples (helloworld).
• HTTP: Handling HTTP-specific tasks like CORS and file uploads (http).
• Websocket: Simple Websocket implementations (ws) and a full chatroom example (chatroom).
• Streaming: Examples involving streaming data (stream).
• MQTT & Real-time: Complex integration of MQTT, Websocket, and RPC via the Real-time Bus Map example (realtimemap).

Infrastructure & Middleware

• Configuration: Using local files and remote configuration centers (config).
• Registry: Using service registries (registry).
• Middleware: Implementing custom middleware (middleware).
• Error Handling: Managing errors within the framework (errors).
• Logging & Observability: Using logging (log), metrics (metrics), tracing (traces), and OpenTelemetry (otel).
• Metadata & Headers: Working with HTTP headers (header) and metadata (metadata).

Data & Patterns

• CQRS: Implementing Command Query Responsibility Segregation, primarily using Kafka (cqrs).
• Messaging: Using Message Queues like Kafka for sending/receiving messages (event).
• Database: Managing database transactions (transaction).
• Validation: Using Protobuf parameter validators (validate).
• CRUD: A simple blog system demonstrating basic Create, Read, Update, and Delete operations (blog).

API Documentation & Utilities

• Swagger: Using Swagger for API documentation (swagger).
• I18n: Implementing internationalization and localization (i18n).
• Selector: Using node selectors (selector).

The examples repository contains various implementations demonstrating different Kratos components and patterns. Use these examples to understand how to implement specific features in your own Kratos projects:

• Core Components:

  • config: Demonstrates Kratos configuration management.
  • errors: Shows how to handle errors, specifically those generated via proto-gen-go-errors.
  • log: Provides examples for logger, helper, filter, and valuer.
  • metadata: Demonstrates usage of metadata.
  • registry: Shows service registration and discovery using Etcd, Consul, and Nacos.
  • validate: Demonstrates middleware-based validation using code generated by proto-gen-validate.

• Transport & Communication:

  • http: Examples of HTTP transport usage.
  • ws: Implementation of the transport interface using WebSockets.
  • swagger: Implementation of a server with embedded Swagger API documentation.

• Observability:

  • metrics: Demonstrates metrics collection using Prometheus (prom).
  • traces: Demonstrates middleware/tracing implemented via OpenTelemetry.

• Application Patterns:

  • blog: A simple CRUD project.
  • helloworld: A basic

In the cqrs/app/logger/service implementation, the project uses the Confluent Go client (confluent-kafka-go/kafka) instead of the Sarama client.

This decision was made to avoid several known issues with the Sarama Go client:

1. Partition Awareness: Sarama cannot detect when new partitions are added to a Topic without a client restart.
2. Multi-Topic Subscription: Subscribing to two or more Topics simultaneously in Sarama can lead to certain partitions failing to consume messages correctly.
3. Offset Reset Risks: When the consumer offset reset strategy is set to Oldest(earliest), Sarama's custom implementation of the OutOfRange mechanism can cause the client to re-consume all messages from the beginning if the client crashes or the server version is upgraded.

For more technical depth on these issues, refer to the documentation provided by Alibaba Cloud or general Kafka development guides.