Skip to content

[C] Generation Microservices

Jump to bottom
Roberto Artigas edited this page Jan 26, 2026 · 1 revision

Code Generation Principles Mapped to Microservices

Applying Non-Negotiable Code Generation Principles in a Microservices Architecture

This document maps the Non-Negotiable Principles for Code Generation (with Anti-Patterns) to a microservices architecture.

Microservices amplify both the benefits and risks of code generation:

  • Done well, generators reduce duplication and enforce consistency at scale.
  • Done poorly, generators create distributed technical debt that is hard to unwind.

This mapping shows how each principle applies concretely in a microservices environment.

Microservices Context: Why This Is Harder

Microservices introduce:

  • many independent codebases,
  • many deployment pipelines,
  • many service owners,
  • long-lived backward compatibility requirements.

Therefore:

Any weakness in code generation multiplies by the number of services.

Principle 1: Full Ownership and Control of Templates

Microservices Interpretation

Each team must own and understand the templates that generate service code.

Good Practices

  • Shared template repositories with versioning (e.g., service-template-vX)
  • Explicit template version pinned per service
  • Clear changelogs for template evolution
  • Ability for teams to fork or replace templates if needed

Microservices Anti-Patterns

  • Central platform team controls opaque generators
  • “Golden template” that teams cannot modify
  • Forced upgrades of templates across services
  • Debugging failures by patching generated service code

Failure Mode at Scale

  • Dozens of services stuck on unmaintainable scaffolding
  • Platform bottlenecks slow all teams simultaneously

Principle 2: Metadata Is a First-Class, Independent Artifact

Microservices Interpretation

Service definitions must exist outside the generated service code.

Good Practices

  • Explicit service descriptors (YAML/JSON/DSL):
    • API contracts
    • data models
    • dependencies
    • deployment metadata
  • Metadata stored per service and validated independently
  • Metadata reused by generators, CI/CD, docs, and observability

Microservices Anti-Patterns

  • Metadata inferred from code annotations only
  • Configuration scattered across repos and pipelines
  • Generator-specific metadata formats no one else can read

Failure Mode at Scale

  • Services drift from their intended contracts
  • Impossible to reason about system topology

Principle 3: Deterministic, One-Click Regeneration

Microservices Interpretation

Any service must be rebuildable from scratch with one command.

Good Practices

  • make generate or equivalent per service
  • Deterministic outputs across machines and CI
  • Regeneration does not depend on existing generated files
  • CI verifies regeneration produces no diff

Microservices Anti-Patterns

  • Manual fixes applied after generation
  • Regeneration requires tribal knowledge
  • Different services regenerate differently

Failure Mode at Scale

  • Inconsistent services
  • Broken disaster recovery
  • Platform upgrades become dangerous

Principle 4: Handcrafted Code Is Protected and Respected

Microservices Interpretation

Business logic inside services must be generator-safe.

Good Practices

  • Clear separation:
    • /generated → disposable
    • /domain or /service → handwritten
  • Explicit extension points (hooks, adapters, ports)
  • Regeneration never touches business logic

Microservices Anti-Patterns

  • Business logic mixed into generated scaffolding
  • “Just edit the generated controller” culture
  • No clear ownership of files

Failure Mode at Scale

  • Teams stop regenerating
  • Divergent service behavior
  • Generator abandonment

Principle 5: Generated Code Must Meet or Exceed Handwritten Quality

Microservices Interpretation

Generated service scaffolding must be production-grade, not demo-grade.

Good Practices

  • Generated services:
    • are testable by default,
    • integrate observability (logs, metrics, traces),
    • handle errors consistently,
    • meet performance baselines.
  • Generated code follows team coding standards

Microservices Anti-Patterns

  • Massive generated frameworks per service
  • Excessive abstraction to “cover all cases”
  • Poor performance hidden behind network calls

Failure Mode at Scale

  • Latency explosions
  • Debugging distributed failures becomes impossible
  • Operational cost overwhelms development speed

Cross-Cutting Microservices Anti-Patterns

“Platform as Generator Dictatorship”

  • Platform team enforces generators without escape hatches
  • Teams lose autonomy
  • Innovation stalls

“Scaffold-and-Freeze”

  • Services generated once and never regenerated
  • Template evolution stops
  • System fragments over time

“Generator-Driven Architecture”

  • Architecture decisions encoded only in templates
  • No ADRs or human review
  • Architecture becomes unchangeable

High-Leverage Microservices Guidelines

  1. Templates define conventions, not behavior
  2. Metadata defines intent; generators enforce consistency
  3. Regeneration must be boring and safe
  4. Service autonomy beats template purity
  5. If a service cannot be regenerated, the generator has failed

Microservices Red Flags

  • “This service is special; don’t regenerate it.”
  • “Only the platform team understands the generator.”
  • “We had to hotfix the generated code.”
  • “Template upgrades are too risky.”

Summary

In microservices:

  • code generation is not optional discipline — it is survival discipline.
  • bad generators scale failure faster than any human mistake.

Used correctly, code generation:

  • enforces consistency,
  • preserves autonomy,
  • and keeps hundreds of services evolvable.

Closing Insight

Microservices reward boring generation and punish clever generation.

The safest generator is the one teams trust enough to run every day.

Code Wiki Main Repositories

Clone this wiki locally