Microservice Development Practices and Standards with Spring Cloud

Maven Standards

All projects must share a unified parent module that manages dependency versions, Maven repositories, and jar version upgrades. Under the parent, custom modules like core, starter, and rate-limit can be defined.

The core module provides POJO-based conventions (e.g., BaseEntity), auto-configuration for third‑party components, and utility classes (XXXUtil). All core dependencies should use provided scope and be conditionally loaded with annotations like @ConditionalOnClass or @ConditionalOnBean .

The starter module aggregates common dependencies for services, while the rate‑limit module houses non‑generic custom components. Proper distinction between Release and Snapshot versions is essential: Snapshot versions are auto‑deployed to snapshot repositories and fetched automatically, whereas Release versions are deployed to the release repository and are not re‑downloaded if the same version exists locally.

Service Invocation Standards

Services should depend on SDKs exposing APIs; consumers import the producer's API and use Snapshot versions for easy upgrades.

account
  account‑api
  account‑service

Example interface definition:

public interface AccountApi {
    ...
}

Implementation of the API in the service:

@RestController
@Log4j2
@Api(tags = "User API")
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
public class AccountController implements AccountApi {
    ...
}

Feign client usage with fallback:

@Component
@FeignClient(name = "account-service", fallbackFactory = AccountClientFallbackFactory.class)
public interface AccountClient extends AccountApi {
    ...
}

@Component
public class AccountClientFallbackFactory implements FallbackFactory
{
    @Override
    public AccountClient create(Throwable throwable) {
        AccountClientFallback fallback = new AccountClientFallback();
        fallback.setCause(throwable);
        return fallback;
    }
}

@Slf4j
public class AccountClientFallback implements AccountClient {
    @Setter
    private Throwable cause;

    @Override
    public ResultData
getByCode(String accountCode) {
        log.error("Query failed, interface exception", cause);
        AccountDTO account = new AccountDTO();
        account.setAccountCode("000");
        account.setAccountName("Test Feign");
        return ResultData.success(account);
    }
}

RESTful Design Standards

API URLs should follow /version/accessControl/domainObject or /version/accessControl/domainObject/action patterns, using nouns for domain objects and proper HTTP methods (GET, POST, PUT, DELETE). Access control levels include pb (public), pt (protected), pv (private), and df (default with token authentication and encryption).

Versioning strategy: upgrade the whole microservice version (e.g., from /v1 to /v2 ) while keeping backward‑compatible endpoints available.

@Deprecated
@PostMapping("/v1/pb/user")

@PostMapping("/{version}/pb/user")

Gateway Guidelines

The gateway may delegate authentication to downstream services or handle it directly for simple cases. It must enforce access control, block special paths like /pv/** , and support gray release by routing traffic based on Nacos metadata and request headers.

Recommended Reading

Links to articles on Redis cache design for billion‑scale systems, design principles for architects, and Spring Boot integration with Kafka are provided for further study.