357 lines
11 KiB
Markdown
357 lines
11 KiB
Markdown
---
|
|
trigger: always_on
|
|
---
|
|
|
|
|
|
# Microservices Development Process
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when:
|
|
- Creating a new microservice from scratch
|
|
- Migrating or refactoring an existing service
|
|
- Planning service implementation with multiple phases
|
|
- Ensuring comprehensive coverage of all development aspects
|
|
- Need structured approach to service development
|
|
|
|
## Development Process Overview
|
|
|
|
The microservices development process follows these phases:
|
|
1. **Planning & Impact Analysis** - Define scope, impact, dependencies
|
|
2. **Foundation Setup** - Service structure, configs, infrastructure
|
|
3. **Core Implementation** - Business logic, APIs, data layer
|
|
4. **Integration** - Routes, middleware, external services
|
|
5. **Testing** - Unit, integration, E2E tests
|
|
6. **Documentation** - API docs, README, guides
|
|
7. **Cleanup & Verification** - Remove temporary files, verify completeness
|
|
8. **Deployment** - Staging deployment, production deployment
|
|
|
|
### Process Flow Diagram
|
|
|
|
```mermaid
|
|
graph TD
|
|
Start([Start: New Service Requirements]) --> Phase1[Phase 1: Planning & Impact Analysis]
|
|
Phase1 --> ImpactCheck{Impact Analysis<br/>Complete?}
|
|
ImpactCheck -->|No| Phase1
|
|
ImpactCheck -->|Yes| Phase2[Phase 2: Foundation Setup]
|
|
|
|
Phase2 --> FoundationCheck{Service Starts<br/>& Health Check Passes?}
|
|
FoundationCheck -->|No| Phase2
|
|
FoundationCheck -->|Yes| Phase3[Phase 3: Core Implementation]
|
|
|
|
Phase3 --> ImplementationCheck{Business Logic<br/>Implemented?}
|
|
ImplementationCheck -->|No| Phase3
|
|
ImplementationCheck -->|Yes| Phase4[Phase 4: Integration]
|
|
|
|
Phase4 --> IntegrationCheck{Routes & Middleware<br/>Working?}
|
|
IntegrationCheck -->|No| Phase4
|
|
IntegrationCheck -->|Yes| Phase5[Phase 5: Testing]
|
|
|
|
Phase5 --> TestCheck{Tests Pass<br/>& Coverage Met?}
|
|
TestCheck -->|No| Phase5
|
|
TestCheck -->|Yes| Phase6[Phase 6: Documentation]
|
|
|
|
Phase6 --> DocCheck{Docs<br/>Complete?}
|
|
DocCheck -->|No| Phase6
|
|
DocCheck -->|Yes| Phase7[Phase 7: Cleanup & Verification]
|
|
|
|
Phase7 --> VerificationCheck{All Checks<br/>Pass?}
|
|
VerificationCheck -->|No| Phase7
|
|
VerificationCheck -->|Yes| Phase8[Phase 8: Deployment]
|
|
|
|
Phase8 --> DeployCheck{Staging<br/>Deployed?}
|
|
DeployCheck -->|No| Phase8
|
|
DeployCheck -->|Yes| Production{Deploy to<br/>Production?}
|
|
Production -->|Yes| ProdDeploy[Production Deployment]
|
|
Production -->|No| Complete([Complete])
|
|
ProdDeploy --> Complete
|
|
|
|
style Phase1 fill:#e1f5ff
|
|
style Phase2 fill:#fff4e1
|
|
style Phase3 fill:#f0e1ff
|
|
style Phase4 fill:#e1ffe1
|
|
style Phase5 fill:#ffe1e1
|
|
style Phase6 fill:#e1ffff
|
|
style Phase7 fill:#fff0e1
|
|
style Phase8 fill:#ffe1f5
|
|
style Complete fill:#d4edda
|
|
```
|
|
|
|
### Detailed Phase Flow
|
|
|
|
```mermaid
|
|
graph LR
|
|
subgraph Planning["Phase 1: Planning"]
|
|
P1A[Define Scope] --> P1B[Impact Analysis]
|
|
P1B --> P1C[Dependencies Map]
|
|
P1C --> P1D[Acceptance Criteria]
|
|
end
|
|
|
|
subgraph Foundation["Phase 2: Foundation"]
|
|
F2A[Copy Template] --> F2B[Configure Package]
|
|
F2B --> F2C[Setup Database]
|
|
F2C --> F2D[Configure Docker]
|
|
F2D --> F2E[Setup Traefik]
|
|
end
|
|
|
|
subgraph Implementation["Phase 3: Implementation"]
|
|
I3A[DTOs] --> I3B[Repository]
|
|
I3B --> I3C[Service]
|
|
I3C --> I3D[Controller]
|
|
I3D --> I3E[Module]
|
|
end
|
|
|
|
subgraph Integration["Phase 4: Integration"]
|
|
IN4A[Register Routes] --> IN4B[Setup Middleware]
|
|
IN4B --> IN4C[External Services]
|
|
IN4C --> IN4D[Health Checks]
|
|
end
|
|
|
|
subgraph Testing["Phase 5: Testing"]
|
|
T5A[Unit Tests] --> T5B[Integration Tests]
|
|
T5B --> T5C[E2E Tests]
|
|
T5C --> T5D[Coverage Check]
|
|
end
|
|
|
|
subgraph Documentation["Phase 6: Documentation"]
|
|
D6A[README] --> D6B[API Docs]
|
|
D6B --> D6C[Architecture Docs]
|
|
end
|
|
|
|
subgraph Cleanup["Phase 7: Cleanup"]
|
|
C7A[Remove Temp Files] --> C7B[Update References]
|
|
C7B --> C7C[Verify Everything]
|
|
end
|
|
|
|
subgraph Deployment["Phase 8: Deployment"]
|
|
DEP8A[Staging] --> DEP8B[Verification]
|
|
DEP8B --> DEP8C[Production]
|
|
end
|
|
|
|
Planning --> Foundation
|
|
Foundation --> Implementation
|
|
Implementation --> Integration
|
|
Integration --> Testing
|
|
Testing --> Documentation
|
|
Documentation --> Cleanup
|
|
Cleanup --> Deployment
|
|
|
|
style Planning fill:#e1f5ff
|
|
style Foundation fill:#fff4e1
|
|
style Implementation fill:#f0e1ff
|
|
style Integration fill:#e1ffe1
|
|
style Testing fill:#ffe1e1
|
|
style Documentation fill:#e1ffff
|
|
style Cleanup fill:#fff0e1
|
|
style Deployment fill:#ffe1f5
|
|
```
|
|
|
|
## Phase 1: Planning & Impact Analysis
|
|
|
|
### Scope Definition
|
|
|
|
Define clearly:
|
|
- **Service Purpose**: What business capability does it provide?
|
|
- **API Surface**: What endpoints are needed?
|
|
- **Data Models**: What data structures are required?
|
|
- **Dependencies**: What services/packages does it depend on?
|
|
- **Breaking Changes**: Any backward compatibility concerns?
|
|
|
|
### Impact Analysis Checklist
|
|
|
|
Before starting implementation, identify all affected areas:
|
|
|
|
**Files to Create:**
|
|
- [ ] Service directory: `services/service-name/`
|
|
- [ ] Prisma schema: `services/service-name/prisma/schema.prisma`
|
|
- [ ] Dockerfile: `services/service-name/Dockerfile`
|
|
- [ ] Service README: `services/service-name/README.md`
|
|
|
|
**Files to Update:**
|
|
- [ ] Root `package.json` workspace config
|
|
- [ ] `deployments/local/docker-compose.yml` - Add service
|
|
- [ ] `infra/traefik/dynamic/routes.yml` - Add routes
|
|
- [ ] `.github/workflows/ci-*.yml` - Add CI workflow (if needed)
|
|
- [ ] Documentation: `docs/en/guides/`, `docs/vi/guides/`
|
|
- [ ] Scripts: `scripts/db/*.sh`, `scripts/dev/*.sh` (if service-specific)
|
|
|
|
**Infrastructure Changes:**
|
|
- [ ] Database: New schema/tables
|
|
- [ ] Redis: New cache keys/patterns (if needed)
|
|
- [ ] Traefik: New routes and services
|
|
- [ ] Observability: New service metrics/traces
|
|
|
|
**Dependencies:**
|
|
- [ ] External: Database, Redis, third-party APIs
|
|
- [ ] Internal: Shared packages (@goodgo/logger, @goodgo/types, etc.)
|
|
- [ ] Other Services: List dependent services
|
|
|
|
## Phase 2: Foundation Setup
|
|
|
|
### Service Structure Creation
|
|
|
|
**Template Usage:**
|
|
```bash
|
|
cp -r services/_template services/new-service-name
|
|
cd services/new-service-name
|
|
# Update package.json name to @goodgo/new-service-name
|
|
```
|
|
|
|
**Required Files:**
|
|
- Service structure from template
|
|
- `package.json` with correct name and dependencies
|
|
- `src/config/app.config.ts` - Configuration with Zod validation
|
|
- `.env.example` - Environment variables template
|
|
- `prisma/schema.prisma` - Database schema
|
|
- `Dockerfile` - Container configuration
|
|
- `jest.config.ts` - Test configuration
|
|
|
|
### Database Setup
|
|
|
|
```bash
|
|
# Create initial migration
|
|
cd services/service-name
|
|
pnpm prisma migrate dev --name init
|
|
pnpm prisma generate
|
|
```
|
|
|
|
### Docker & Infrastructure
|
|
|
|
**Docker Compose Integration:**
|
|
Add service to `deployments/local/docker-compose.yml` with:
|
|
- Build context and dockerfile
|
|
- Environment variables
|
|
- Traefik labels for routing
|
|
- Health check configuration
|
|
|
|
**Traefik Routes:**
|
|
Update `infra/traefik/dynamic/routes.yml` with:
|
|
- Router rules (PathPrefix)
|
|
- Service configuration
|
|
- Middleware chain (CORS, rate-limit, auth)
|
|
|
|
### Acceptance Criteria for Phase 2
|
|
|
|
- [ ] Service directory created from template
|
|
- [ ] `package.json` configured correctly
|
|
- [ ] Environment variables defined
|
|
- [ ] Prisma schema created and migration run
|
|
- [ ] Service starts: `pnpm dev` (health check passes)
|
|
- [ ] Docker build succeeds
|
|
- [ ] Service accessible via Traefik
|
|
- [ ] No TypeScript errors: `pnpm typecheck`
|
|
|
|
## Phase 3: Core Implementation
|
|
|
|
### Module Structure
|
|
|
|
Each feature module follows this pattern:
|
|
```
|
|
modules/feature-name/
|
|
├── feature.controller.ts # HTTP handlers
|
|
├── feature.service.ts # Business logic
|
|
├── feature.repository.ts # Data access
|
|
├── feature.dto.ts # Validation schemas (Zod)
|
|
├── feature.module.ts # Module registration
|
|
└── index.ts # Public exports
|
|
```
|
|
|
|
### Implementation Flow
|
|
|
|
```mermaid
|
|
graph TD
|
|
Start[Start Implementation] --> DTOs[1. Create DTOs<br/>Zod Validation Schemas]
|
|
DTOs --> Repo[2. Create Repository<br/>Prisma Data Access]
|
|
Repo --> Service[3. Create Service<br/>Business Logic]
|
|
Service --> Controller[4. Create Controller<br/>HTTP Handlers]
|
|
Controller --> Module[5. Create Module<br/>Wire Up Components]
|
|
Module --> Test[Manual Testing]
|
|
Test --> Pass{Tests Pass?}
|
|
Pass -->|No| Repo
|
|
Pass -->|Yes| Next[Next Feature Module]
|
|
|
|
style DTOs fill:#e1f5ff
|
|
style Repo fill:#fff4e1
|
|
style Service fill:#f0e1ff
|
|
style Controller fill:#e1ffe1
|
|
style Module fill:#ffe1e1
|
|
```
|
|
|
|
### Implementation Order
|
|
|
|
1. **DTOs** - Zod schemas for request/response validation
|
|
2. **Repository** - Prisma-based data access, CRUD operations
|
|
3. **Service** - Business logic, error handling, validation
|
|
4. **Controller** - HTTP request handling, standardized responses
|
|
5. **Module** - Wire up components, export router
|
|
|
|
### Code Patterns
|
|
|
|
**Repository:** Extend base Repository, use Prisma client for data access
|
|
**Service:** Inject repository, implement business logic, use logger
|
|
**Controller:** Handle HTTP requests, validate with DTOs, call services
|
|
**Module:** Wire up dependencies, export router
|
|
|
|
### Acceptance Criteria for Phase 3
|
|
|
|
- [ ] All DTOs defined with Zod validation
|
|
- [ ] Repository methods implemented
|
|
- [ ] Service business logic implemented
|
|
- [ ] Controllers handle requests correctly
|
|
- [ ] Modules configured properly
|
|
- [ ] No TypeScript errors
|
|
- [ ] Manual API testing successful
|
|
|
|
## Phase 4: Integration
|
|
|
|
### Route Registration
|
|
|
|
Update `src/routes/index.ts`:
|
|
- Import feature modules
|
|
- Create router instances
|
|
- Register routes with path prefixes
|
|
- Mount to main app with `/api/v1/service-name` prefix
|
|
|
|
### Middleware Setup
|
|
|
|
**Required Middlewares (in order):**
|
|
1. Correlation middleware
|
|
2. Logging middleware
|
|
3. Metrics middleware
|
|
4. CORS middleware
|
|
5. Rate limiting middleware
|
|
6. Authentication middleware (if needed)
|
|
7. Error middleware (always last)
|
|
|
|
### External Service Integration
|
|
|
|
- HTTP clients: Use `@goodgo/http-client` for external APIs
|
|
- Redis caching: Implement cache patterns for frequently accessed data
|
|
- Error handling: Handle external service failures gracefully
|
|
|
|
### Acceptance Criteria for Phase 4
|
|
|
|
- [ ] All routes registered and accessible
|
|
- [ ] Middlewares applied in correct order
|
|
- [ ] Error handling works for all scenarios
|
|
- [ ] External services integrated (if any)
|
|
- [ ] Caching implemented (if needed)
|
|
- [ ] Health check endpoint works: `/health`
|
|
|
|
## Phase 5: Testing
|
|
|
|
### Test Structure
|
|
|
|
**Unit Tests:** Next to source files (`*.test.ts`), mock all dependencies
|
|
**Integration Tests:** `src/__tests__/`, test component interactions
|
|
**E2E Tests:** `src/__tests__/*.e2e.ts`, test full API workflows
|
|
|
|
### Test Coverage Targets
|
|
|
|
- Minimum: 70% coverage (branches, functions, lines, statements)
|
|
- Critical paths: 90%+ coverage
|
|
- Repositories: 80%+ coverage
|
|
- Services: 80%+ coverage
|
|
- Controllers: 70%+ coverage
|
|
|