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.
✅ DO ensure all Java packages are named using the form
✅ 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.
✅ DO use the group ID of
✅ DO specify the
artifactId to be of the form
azure-spring-boot-starter-<group>-<service>[-<feature>], for example,
For Spring data abstraction, the
artifactId should be of the form
For Spring cloud starters, the
artifactId should be of the form
✅ 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.
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 latest release version of Spring API dependencies in the Spring integration module POM files, it is the users responsibility to override the Spring API version via Spring BOM.
✅ 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
✅ DO provide a Spring integration modules 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.
✅ DO encourage users to use the Spring integration modules 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.
⛔️ 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.
⛔️ DO NOT use the
ClientLogger logging APIs.
✅ 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.
✅ 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.