138 lines
4.1 KiB
Markdown
138 lines
4.1 KiB
Markdown
# Microservices Architecture Template
|
|
|
|
Use this template when designing a microservices-based system.
|
|
|
|
## Service Definition
|
|
|
|
- **Service name:** [ServiceName]
|
|
- **Bounded context:** [Domain boundary this service owns]
|
|
- **Team owner:** [Team responsible for this service]
|
|
|
|
## Service Responsibilities
|
|
|
|
- **Core capabilities:**
|
|
- [Primary business capability 1]
|
|
- [Primary business capability 2]
|
|
- **Data ownership:**
|
|
- [Entities this service owns]
|
|
- [Events this service publishes]
|
|
|
|
## API Contract
|
|
|
|
### REST Endpoints
|
|
|
|
```http
|
|
GET /api/v1/[resource]
|
|
POST /api/v1/[resource]
|
|
PUT /api/v1/[resource]/{id}
|
|
DELETE /api/v1/[resource]/{id}
|
|
```
|
|
|
|
### Events Published
|
|
|
|
- **[EventName]**: Published when [trigger condition]
|
|
- **[EventName]**: Published when [trigger condition]
|
|
|
|
### Events Consumed
|
|
|
|
- **[EventName]**: From [SourceService], triggers [action]
|
|
|
|
## Dependencies
|
|
|
|
### Upstream Services (Calls)
|
|
|
|
- **[ServiceName]**: For [purpose], timeout: [Xms], circuit breaker threshold: [N failures]
|
|
|
|
### Downstream Services (Called by)
|
|
|
|
- **[ServiceName]**: Expects [SLA], provides [data/functionality]
|
|
|
|
## Data Storage
|
|
|
|
- **Database type:** [PostgreSQL / MongoDB / Cassandra / etc.]
|
|
- **Schema approach:** [Database-per-service / Shared tables / etc.]
|
|
- **Replication:** [Primary-replica / Multi-master]
|
|
- **Backup strategy:** [Automated daily / Point-in-time recovery]
|
|
|
|
## Resilience
|
|
|
|
- **Timeouts:**
|
|
- Database queries: [Xms]
|
|
- External API calls: [Xms]
|
|
- Internal service calls: [Xms]
|
|
- **Retry policy:** Exponential backoff, max [N] retries
|
|
- **Circuit breaker:** Open after [N] failures, half-open after [X] seconds
|
|
- **Rate limiting:** [N] requests per second per client
|
|
- **Fallback behavior:** [Return cached data / Default response / Graceful degradation]
|
|
|
|
## Observability
|
|
|
|
- **Metrics:**
|
|
- Request rate, latency (p50, p95, p99)
|
|
- Error rate (4xx, 5xx)
|
|
- Dependency health
|
|
- Business metrics: [specific to service]
|
|
- **Distributed tracing:** Jaeger/OpenTelemetry with trace IDs
|
|
- **Logging:**
|
|
- Structured JSON logs
|
|
- Log level: INFO in production, DEBUG in dev
|
|
- Key fields: trace_id, user_id, service_name, timestamp
|
|
- **Health checks:**
|
|
- Liveness: `/health/live` (basic ping)
|
|
- Readiness: `/health/ready` (dependencies check)
|
|
|
|
## Deployment
|
|
|
|
- **Container:** Docker image, registry: [ECR / Docker Hub / etc.]
|
|
- **Orchestration:** Kubernetes
|
|
- **Scaling policy:**
|
|
- Min replicas: [N]
|
|
- Max replicas: [N]
|
|
- Scale trigger: CPU > [X]% or Memory > [X]% or RPS > [N]
|
|
- **Deployment strategy:** Rolling update / Canary / Blue-green
|
|
- **Rollback plan:** Automated rollback if error rate > [X]%
|
|
|
|
## Security
|
|
|
|
- **Authentication:** JWT tokens, validated via [Auth service / API Gateway]
|
|
- **Authorization:** Role-based access control (RBAC)
|
|
- **Service-to-service auth:** mTLS via service mesh
|
|
- **Secrets:** Stored in [AWS Secrets Manager / Vault / Kubernetes Secrets]
|
|
- **Input validation:** All user inputs validated and sanitized
|
|
- **Rate limiting:** Per-user and per-IP limits
|
|
|
|
## Testing
|
|
|
|
- **Unit tests:** Coverage target: 80%+
|
|
- **Integration tests:** Test API contracts and database interactions
|
|
- **Contract tests:** Pact/Spring Cloud Contract for upstream/downstream
|
|
- **Load tests:** Target [N] RPS at p95 < [Xms]
|
|
- **Chaos testing:** Simulate dependency failures, network latency
|
|
|
|
## Communication Patterns
|
|
|
|
- **Synchronous:** REST/gRPC for request-response
|
|
- **Asynchronous:** Kafka/RabbitMQ for events
|
|
- **Idempotency:** All write operations support idempotency keys
|
|
- **Message format:** JSON for REST, Protobuf for gRPC, Avro for Kafka
|
|
|
|
## Cost Optimization
|
|
|
|
- **Resource allocation:**
|
|
- CPU request: [Xm], limit: [Xm]
|
|
- Memory request: [XMi], limit: [XMi]
|
|
- **Auto-scaling:** Scale down during off-peak hours
|
|
- **Data retention:** [X days] for logs, [X days] for metrics
|
|
|
|
## Migration Plan
|
|
|
|
- **Phase 1:** [Extract service from monolith / Build new service]
|
|
- **Phase 2:** [Gradual traffic migration / Feature flag rollout]
|
|
- **Phase 3:** [Full cutover / Decommission old system]
|
|
- **Rollback criteria:** [Error rate / Latency / Business metrics]
|
|
|
|
## ADR References
|
|
|
|
- [ADR-001]: [Decision about technology choice]
|
|
- [ADR-002]: [Decision about data model]
|