Principle:Apache Shardingsphere YAML Configuration Definition
| Knowledge Sources | |
|---|---|
| Domains | Configuration_Management, Shadow_Testing |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Defining database rules through structured YAML configuration files that map to typed Java objects via annotation-driven deserialization.
Description
YAML Configuration Definition is a design pattern in which database rule configurations are expressed as structured YAML documents and mapped directly onto typed Java objects. In this pattern, each rule module declares a dedicated YAML configuration class that serves as the deserialization target. The class uses field-level annotations to denote the semantic role of each property (for example, data source mappings, table definitions, or algorithm references). The Java class mirrors the hierarchical structure of the YAML document, establishing a one-to-one correspondence between YAML keys and Java fields.
This approach has several advantages:
- Type Safety: Configuration values are bound to strongly-typed Java fields at deserialization time, catching structural errors early rather than at runtime.
- Self-Documenting Structure: The YAML configuration class itself acts as the schema definition. By examining the class fields and their types, the valid configuration structure is fully determined without external schema files.
- Annotation-Driven Metadata: Field-level annotations such as
@RuleNodeTupleFieldcarry metadata about how each configuration section should be persisted and managed in distributed governance nodes. This decouples persistence concerns from the data structure itself. - Default Initialization: Fields are initialized with empty collections (e.g.,
new LinkedHashMap<>()) so that the deserialized object is always in a valid, non-null state even when optional YAML sections are omitted.
The pattern requires a companion YAML configuration class for each sub-element (such as data source pairs and table definitions), creating a compositional hierarchy that mirrors the YAML document tree.
Usage
Use this pattern whenever a new rule module needs to accept user-provided configuration from YAML files. It is the standard entry point for all rule configuration in ShardingSphere. The YAML configuration class is consumed by the YAML parsing engine during application startup or dynamic configuration reload, and is subsequently converted into a domain configuration object by a dedicated swapper.
Theoretical Basis
The YAML Configuration Definition pattern follows a declarative data binding approach. The theoretical workflow is:
1. Define a YAML configuration class C that implements YamlRuleConfiguration
2. For each configuration section S in the rule:
a. Create a nested YAML configuration class C_S implementing YamlConfiguration
b. Add a field of type Map<String, C_S> or Collection<C_S> to C
c. Annotate the field with @RuleNodeTupleField(type = <semantic_type>)
3. Initialize all collection/map fields with empty defaults
4. Implement getRuleConfigurationType() to return the domain config class
5. The YAML engine deserializes documents into C by matching YAML keys to field names
6. A swapper transforms C into the domain configuration object
The key invariant is that the YAML document structure must exactly match the field names declared in the configuration class hierarchy. The annotation metadata is consumed by the governance layer for configuration persistence and change notification, not by the deserialization engine itself.
The class-level annotation @RuleNodeTupleEntity("shadow") establishes the rule type identity used for governance node path construction. Each @RuleNodeTupleField with a Type value (DATA_SOURCE, TABLE, ALGORITHM, DEFAULT_ALGORITHM) defines how that configuration section is stored and retrieved in the distributed configuration center.