Providing the Spring ecosystem with a first-class experience is of the utmost importance. The guidelines below are in addition to the standard Java design guidelines, overriding the guidance as appropriate.
Namespaces
✅ DO ensure all Java packages are named using the form com.azure.spring.<group>.<service>[.<feature>].
✅ DO use the same group, service, and feature naming as is used by the underlying Java client library.
✅ DO put all non-public API under an implementation package under the root namespace.
Maven
✅ DO use the group ID of com.azure.
✅ DO specify the artifactId to be of the form azure-spring-boot-starter-<group>-<service>[-<feature>], for example, azure-spring-boot-starter-storage-blob or azure-spring-boot-starter-security-keyvault-secrets.
✅ DO include a dependencyManagement dependency on the Azure Java SDK BOM, so that users who use Azure Spring libraries can bring in additional dependencies on other Azure Java client libraries without needing to choose versions.
Versioning
Spring integration modules must be versioned in a way that enables the following goals:
- Each Spring integration module must be able to release at different release cadences.
- Each Spring integration module must have full semantic versioning for major, minor, and patch versions, in all releases. Versioning must not be tied to the Spring dependency version as in earlier iterations of the Azure Spring integration modules.
- Allow developers to easily choose Spring integration modules which work together.
✅ DO ensure that all releases of a Spring integration module support all active versions (as of the time of release) of the corresponding Spring API.
✅ DO add Spring API dependencies as provided in the Spring integration module POM files, so that it is the users responsibility to provide a specific dependency in their own codebase.
✅ DO add Maven classifiers to releases if a Spring integration module cannot support all active versions of the corresponding Spring API. For example, if a Spring integration module needs to support Spring Boot 2.2.x and 2.3.x, but cannot due to technical contraints, two versions of the Spring integration module must be released, with classifiers springboot_2_2 and springboot_2_3.
✅ DO provide a Spring-specific BOM for users. This BOM must contain versions of all Spring integration modules that are known to work together (and have a single set of dependency versions). It must also include appropriate references to Azure Java SDK and Spring BOMs.
✅ DO name the Spring-specific BOM specifically after the corresponding Spring version, e.g. azure-spring-boot-2-2-bom.
✅ DO encourage users to use the Spring-specific BOM for their chosen version of Spring rather than specific versions of each Spring integration module, such that they need not worry about Maven classifiers and other versioning issues.
Dependencies
⛔️ DO NOT introduce dependencies on libraries, or change dependency versions, without discussion with the Java architect. Each dependency must receive explicit approval and be added to the dependency allow list before it may be used.
⛔️ DO NOT introduce dependencies on library versions that conflict with the transitive dependencies of Spring libraries.
✅ DO make use of com.azure client libraries only - do not mix older com.microsoft.azure client libraries into the dependency hierarchy.
✅ DO keep dependencies to the minimal required set.
Logging
⛔️ DO NOT use the ClientLogger logging APIs.
Tracing
✅ DO ensure that all Azure Spring libraries fully integrate with the tracing capabilities available in the Azure Java client libraries.
✅ DO ensure that all Azure Spring libraries work appropriately with Spring Sleuth, and that tracing information is appropriately exported.
Performance
✅ DO ensure, through appropriate benchmarks (developed in conjuction with the Java SDK team) that performance of all Spring libraries is at an equivalent level to the same operation being performed directly through the Java client library.