Service Versioning & Compatibility

RPC services evolve over time and need versioning and compatibility strategies for multi-version coexistence, gradual rollout, and phased deprecation. This article covers version numbers, groups, and compatibility rules with a practical table.

Overview

• Version: Providers expose a version; consumers reference the version they call. UserService:1.0 and UserService:2.0 can coexist; consumers choose as needed.
• Group: Further partition within a version for environment isolation (test/prod), read/write split, or canary.
• Compatibility: When the interface changes, preserve backward compatibility. Adding optional parameters, new methods, or new return fields is usually compatible. Removing methods, changing parameter types, or removing fields is incompatible; handle via a new version or new interface.
• Serialization: Protobuf and JSON handle field add/remove differently; consider evolution when choosing.

Example

Example 1: Dubbo version and group

XMLCopy
<dubbo:service interface="UserService" version="1.0" group="prod"/>
<dubbo:service interface="UserService" version="2.0" group="gray"/>
<dubbo:reference interface="UserService" version="1.0" group="prod"/>

• During canary, some consumers switch to version=2.0, group=gray; after validation, roll out fully.

Example 2: Compatibility rules

Change	Compatible?	Recommendation
Add optional parameter	Yes	Default value or overload
Add method	Yes	-
Add return field	Usually yes	Client ignores unknown fields
Remove method/parameter/field	No	New version, deprecation period, dual-write transition
Change parameter/return type	No	New method or new version

Example 3: Evolution flow

1. Deploy new-version provider alongside the old one.
2. Some consumers switch to the new version in canary.
3. After full switch, decommission the old provider.
4. Old version enters deprecation period and is eventually removed.

Core Mechanism / Behavior

• Version routing: Registry stores providers by version and group. Consumers filter by version/group in the reference config.
• Compatibility: Schema-based formats (Protobuf) have explicit rules; schema-less (JSON) rely on conventions. Document and follow them.

Key Rules

• Assess compatibility before changes; use a new version or new method for incompatible changes and allow a transition period.
• Use version and group for canary and isolation; switch dynamically via config center or routing rules to reduce risk.
• Document version and deprecation plans; follow serialization evolution rules.

What's Next

See Serialization Tradeoffs for format and compatibility. See Dubbo Architecture and Load Balancing for multi-version routing. See Blue-Green vs Canary for deployment strategy.