miso

---
name: miso
description: Use the miso Go framework for backend microservices. Use when working with the miso framework (https://github.com/curtisnewbie/miso) for: (1) Creating new microservices with component-based architecture, (2) Implementing RESTful APIs with Gin integration, (3) Database operations with GORM, (4) Configuration management with Viper, (5) Error handling with structured MisoErr types, (6) Distributed tracing via Rail context, (7) Distributed tasks with cron scheduling, (8) Bootstrap lifecycle management, (9) Service discovery and middleware integration, (10) Health checks and monitoring, (11) Performance profiling with pprof/FlightRecorder, (12) Request validation, (13) Caching strategies, (14) Kafka messaging, (15) Utility middleware (crypto, JWT, expr, Lua, money, ZooKeeper), (16) Util packages (atom.Time, json, strutil, slutil, retry, randutil, async, osutil, testutil, flags, excel, copyutil), (17) HTTP reverse proxy (HttpProxy) with filter pipelines, config-driven dynamic access filters (whitelist, bearer/basic/remote auth), and WebSocket access control
license: Apache-2.0
---

# Miso Framework

Component-based Go microservices framework with ordered bootstrap lifecycle, distributed tracing, and pluggable middleware architecture.

## Core Concepts

miso is a Go framework for building microservices with:

- **Component Bootstrap** - Ordered component lifecycle (L1→L2→L3→L4) for clean initialization
- **Distributed Tracing** - Rail context for request tracing and structured logging
- **Distributed Tasks** - Cron-based scheduling with master-worker architecture using Redis
- **Web Server** - Gin integration with automatic error handling and API documentation
- **Database Middleware** - GORM integration with MySQL/SQLite support
- **Configuration Management** - Viper-based config with type-safe property constants
- **Error Handling** - Structured error types with context and stack traces
- **HTTP Client** - Service discovery and HTTP client utilities

## Quick Reference

**Rail (Tracing & Logging):** [rail.md](references/rail.md)
- Rail creation, span lifecycle, trace propagation, logging methods

**Bootstrap (Component Lifecycle):** [bootstrap.md](references/bootstrap.md)
- Order levels, component registration, lifecycle callbacks, shutdown hooks

**Web Development:** [web-development.md](references/web-development.md)
- Routing, API patterns, middleware, misoapi code generation

**Database:** [database.md](references/database.md)
- GORM usage, transactions, migrations, dbquery API, recommended default DDL schema

**Configuration:** [configuration.md](references/configuration.md)
- Viper-based config, property constants, default values

**Error Handling:** [error-handling.md](references/error-handling.md)
- Error types, wrapping, logging patterns with Rail

**Distributed Tasks:** [distributed-tasks.md](references/distributed-tasks.md)
- Cron scheduling, master-worker pattern, task queues, hooks

**Service Discovery:** [service-discovery.md](references/service-discovery.md)
- Nacos/Consul service registration, HTTP client with service discovery

**HTTP Proxy:** [http-proxy.md](references/http-proxy.md)
- HttpProxy reverse proxy, filter pipeline, AddConfDynAccessFilter config-driven dynamic access control (whitelist, bearer/basic/remote auth)

**CLI Tools:** [cmd-tools.md](references/cmd-tools.md)
- misogen, misoapi, misocurl, misopatch, misoconfig

**Health Checks:** [health-checks.md](references/health-checks.md)
- Health indicators, status monitoring

**Validation:** [validation.md](references/validation.md)
- Struct validation rules, custom error messages, recursive validation

**Performance Monitoring:** [performance-monitoring.md](references/performance-monitoring.md)
- pprof profiling, FlightRecorder traces, gops inspection

**Caching:** [caching.md](references/caching.md)
- Local cache, TTL cache, Redis cache, cache patterns

**Redis API:** [redis.md](references/redis.md)
- Raw Redis operations, hash/list/set, distributed locks, scripting

**Kafka:** [kafka.md](references/kafka.md)
- Produce/consume messages, listener semantics, partition ordering, trace propagation

**Utility Middleware:** [middleware-utils.md](references/middleware-utils.md)
- crypto, JWT, expr, Lua, money, ZooKeeper leader election

**Util Packages:** [util.md](references/util.md)
- atom.Time (always use instead of time.Time), json, strutil, slutil, retry, randutil, IDs, async, osutil, testutil, flags, excel, copyutil

**Prometheus Metrics:** [prometheus.md](references/prometheus.md)
- Histogram/Counter/HistogramVec constructors, HistTimer/VecTimer, scrape endpoint config, Push Gateway

**Golang Coding Practice:** [golang-coding-practice.md](references/golang-coding-practice.md)
- Defer close resources, never panic, compile regexp once, functional options, shutdown-aware tasks, lock-based concurrency protection