AgentSkillsCN

java-contract-testing

通过兼容性门禁，建立契约式测试（OpenAPI + 消费者驱动的契约），以预防微服务中的重大变更。当API演进可能对消费者造成破坏，或您需要通过CI强制执行向后兼容性时，可使用此技能。

SKILL.md
--- frontmatter
name: java-contract-testing
description: Establish contract testing (OpenAPI + consumer-driven contracts) with compatibility gates to prevent breaking changes in microservices. Use when API evolution risks breaking consumers or when you need CI enforcement of backward compatibility.
license: CC-BY-4.0
compatibility:
  jdk: "17+"
  build: "Maven or Gradle"
  ci: "Any (GitHub Actions/GitLab/Jenkins)"
metadata:
  owner: backend-platform
  version: "0.1.0"
  tags: [java, contract-testing, openapi, pact, ci, microservices]

Java Contract Testing (Compatibility Gates)

What “contract testing” means here

A contract is an executable agreement between a provider and its consumers:

  • •REST: OpenAPI spec (provider contract-first) and/or consumer-driven contract tests
  • •Messaging: event schema + invariants (compatibility rules and verification)

This skill focuses on two complementary strategies:

  1. •Provider-driven contracts (OpenAPI as source of truth)
  2. •Consumer-driven contracts (Pact-style thinking)

Use one, or combine both in a mature platform.

Scope

In scope

  • •OpenAPI spec ownership, versioning, and breaking-change rules
  • •Consumer-driven contracts (Pact JVM style)
  • •CI “compatibility gates”:
    • •fail PRs that introduce breaking changes
    • •require provider verification against published consumer contracts
  • •Contract publishing and verification workflows

Out of scope

  • •End-to-end tests across live services
  • •Performance/load testing

When to use (Triggers)

  • •You have multiple consumers per service
  • •You ship frequently and want to prevent accidental breakages
  • •You experienced production incidents caused by API changes
  • •You need a “deploy safety check” for microservices

Contract strategy decision guide

Strategy A: OpenAPI-first (provider contract)

Pick when:

  • •REST API is primary integration surface
  • •You want one canonical API definition

You do:

  • •Maintain OpenAPI in repo
  • •Generate clients/stubs (optional)
  • •Validate implementation matches OpenAPI
  • •Use OpenAPI diff gate to detect breaking changes

Strategy B: Consumer-driven (Pact)

Pick when:

  • •Many consumers evolve independently
  • •You want consumers to define the minimum they require

You do:

  • •Consumer tests produce contracts (pacts)
  • •Publish contracts to a broker/artifact store
  • •Provider verification runs against published contracts
  • •CI gate blocks deployment if verification fails (“can I deploy?” model)

Strategy C: Hybrid (recommended for large orgs)

  • •OpenAPI as public contract + docs
  • •Pact to enforce real consumer expectations
  • •Both can coexist if governance is clear

Versioning & compatibility rules (REST mindset)

Define and document rules such as:

  • •Non-breaking:
    • •add optional response fields
    • •add new endpoints
    • •widen enum with backward-compatible behavior (case-by-case)
  • •Breaking:
    • •remove fields or endpoints
    • •change field type/meaning
    • •change required/optional in incompatible direction
    • •change error model semantics without version bump

Always encode rules into a gate:

  • •A tool-based diff gate (OpenAPI diff)
  • •A contract verification gate (Pact provider verification)

Implementation workflow (Step-by-step)

Step 1: Define contract storage layout

Recommended:

  • •api/openapi/service.yaml (or openapi.yaml)
  • •contracts/ for pact files or DSL contracts
  • •docs/api/ for rendered docs (optional)

Step 2: Add contract checks to CI

Minimal gates:

  • •Gate 1 (PR): OpenAPI lint + breaking-change detection
  • •Gate 2 (PR/merge): Provider verification against consumer contracts
  • •Gate 3 (pre-deploy): “Can I deploy?” gate based on published verification status

Step 3: Consumer-driven contract workflow (Pact JVM style)

Consumer side:

  1. •Write consumer tests that define interactions (requests + minimal expected responses)
  2. •Generate pact files
  3. •Publish pacts (broker or artifact registry)

Provider side:

  1. •Fetch latest relevant pacts from broker
  2. •Run provider verification tests (against real implementation)
  3. •Publish verification results back to broker
  4. •Gate deployments based on verification status

Step 4: Provider-driven OpenAPI workflow

Provider side:

  1. •OpenAPI spec updated in PR
  2. •CI runs:
    • •spec validation (syntax + lint)
    • •compatibility diff against main branch spec
    • •optionally: API conformance tests that validate endpoints align with spec
  3. •On merge, publish:
    • •rendered docs
    • •versioned spec artifact

Consumers:

  • •Generate client (optional) or validate request/response models against the spec

Practical patterns (to avoid contract rot)

  • •Keep contracts minimal: specify only what is required
  • •Avoid over-constraining with transient details (timestamps, ids formatting) unless truly required
  • •Use stable error model conventions
  • •Treat contracts as “deploy gates”, not “documentation only”

CI Gate templates (conceptual)

Gate: PR compatibility (OpenAPI)

  • •Validate OpenAPI syntax + lint
  • •Compute diff vs base branch spec
  • •Fail if breaking changes found
  • •Output: diff report artifact

Gate: Provider verification (Pact)

  • •Run provider verification suite in CI
  • •Publish verification results
  • •Fail PR if verification fails

Gate: Deploy safety (Pact “can-i-deploy” style)

  • •Before deployment:
    • •check whether current service version is safe to deploy given all published contracts
  • •Block deployment if unsafe

Definition of Done (DoD)

  • • Contract exists in repo and is versioned
  • • PR gate blocks breaking changes (or requires version bump)
  • • Provider verification runs in CI
  • • Consumers can independently validate compatibility
  • • Contracts are discoverable (docs, broker, artifacts)

Guardrails (What NOT to do)

  • •Never treat OpenAPI/pacts as “nice-to-have docs” without enforcement
  • •Never publish contracts without a verification workflow
  • •Avoid:
    • •giant contracts that encode every possible response detail
    • •skipping backward compatibility analysis (“just change it and hope”)

Outputs / Artifacts

  • •OpenAPI spec in repo
  • •Pact contracts (consumer output)
  • •Provider verification test suite
  • •CI jobs: compatibility gate + verification gate
  • •Reports: breaking changes diff + verification status

References (official docs)