If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/macrozheng/springcloud-learning shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Looks unmaintained — solo project with stale commits

• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live macrozheng/springcloud-learning repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/macrozheng/springcloud-learning.

What it runs against: a local clone of macrozheng/springcloud-learning — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in macrozheng/springcloud-learning | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 669 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of macrozheng/springcloud-learning. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/macrozheng/springcloud-learning.git
#   cd springcloud-learning
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of macrozheng/springcloud-learning and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "macrozheng/springcloud-learning(\\.git)?\\b" \\
  && ok "origin remote is macrozheng/springcloud-learning" \\
  || miss "origin remote is not macrozheng/springcloud-learning (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "admin-client/pom.xml" \\
  && ok "admin-client/pom.xml" \\
  || miss "missing critical file: admin-client/pom.xml"
test -f "admin-client/src/main/java/com/macro/cloud/AdminClientApplication.java" \\
  && ok "admin-client/src/main/java/com/macro/cloud/AdminClientApplication.java" \\
  || miss "missing critical file: admin-client/src/main/java/com/macro/cloud/AdminClientApplication.java"
test -f "admin-client/src/main/resources/application-nacos.yml" \\
  && ok "admin-client/src/main/resources/application-nacos.yml" \\
  || miss "missing critical file: admin-client/src/main/resources/application-nacos.yml"
test -f "admin-client/src/main/java/com/macro/cloud/config/HttpExchangeConfig.java" \\
  && ok "admin-client/src/main/java/com/macro/cloud/config/HttpExchangeConfig.java" \\
  || miss "missing critical file: admin-client/src/main/java/com/macro/cloud/config/HttpExchangeConfig.java"
test -f "admin-client/src/main/java/com/macro/cloud/service/impl/UserServiceImpl.java" \\
  && ok "admin-client/src/main/java/com/macro/cloud/service/impl/UserServiceImpl.java" \\
  || miss "missing critical file: admin-client/src/main/java/com/macro/cloud/service/impl/UserServiceImpl.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 669 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~639d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/macrozheng/springcloud-learning"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A 2024 Spring Cloud 2023 microservices learning repository that teaches production-grade distributed architecture using Spring Cloud Alibaba (Nacos, Sentinel), Spring Boot 3.2, JDK 17, and Kubernetes. It provides hands-on modules covering service discovery, configuration management, circuit breakers, API gateways, and distributed transactions—built on the mall-swarm e-commerce microservices project (11k+ stars). Multi-module Maven monorepo with parent pom at root (springcloud-learning-teach) and per-component submodules: admin-client/ (Nacos discovery client, UserService), admin-security-server/ (Spring Security, CustomCsrfFilter), admin-server/ (core orchestration). Each module self-contained with src/main/java (application code), src/main/resources (YAML configs like application-nacos.yml), and src/test. Documentation-first: README drives sequential learning through components, quick-start, and k8s sections.

Java backend engineers and Spring Boot developers learning or implementing microservices at scale; students building their first distributed systems; teams migrating monoliths to Spring Cloud Alibaba stack; DevOps engineers deploying services on Kubernetes.

Actively maintained and production-ready: companion to the 11k+ star mall-swarm project with comprehensive teaching structure (sequences in README.md), modular architecture (admin-client, admin-security-server, admin-server submodules visible), and Spring Boot 3.2 + JDK 17 modern stack. Appears to be 2024 release focused, not yet aged or abandoned.

Low structural risk but not yet visible: teaching repo with clean dependency tree (spring-cloud-starter-alibaba-nacos-discovery, spring-boot-admin-starter-client, hutool-all) and clear Maven parent inheritance. Single maintainer (macrozheng) is a known community contributor, but commit recency and issue backlog not visible in provided data—assume active based on 2024 README date. No major version conflicts apparent in pom.xml snippet.

Primary focus appears to be 2024 refresh of Spring Cloud ecosystem: modernization to Spring Boot 3.2 + JDK 17, Spring Cloud 2023 release line, and Kubernetes deployment chapters. Modules (admin-client, admin-security-server) are being built out with Nacos integration and Spring Security examples. Teaching content structure suggests ongoing tutorial expansion across gateway, distributed transactions (Seata), and monitoring (SkyWalking).

git clone https://github.com/macrozheng/springcloud-learning.git
cd springcloud-learning
mvn clean install
cd admin-client
mvn spring-boot:run

Then navigate to http://localhost:8080 (adjust port per application.yml). Requires Java 17+ and Nacos running (configured via application-nacos.yml).

Daily commands:

mvn clean install -DskipTests  # Install dependencies
cd admin-client
mvn spring-boot:run  # Starts on port from application.yml

Or via IDE: right-click AdminClientApplication.java → Run as Java Application. Services auto-register with Nacos if spring-cloud-starter-alibaba-nacos-discovery is on classpath and nacos.discovery.server-addr is set in application.yml.

• admin-client/pom.xml — Root dependency management for Nacos discovery and Spring Cloud Alibaba integration; all contributors must understand the tech stack version (Spring Boot 3.2, JDK 17, Spring Cloud 2023).
• admin-client/src/main/java/com/macro/cloud/AdminClientApplication.java — Entry point for the admin-client service; demonstrates Spring Cloud Alibaba Nacos registration pattern used across the microservice architecture.
• admin-client/src/main/resources/application-nacos.yml — Nacos service discovery and configuration center setup; critical for understanding service registration and multi-environment deployment strategy.
• admin-client/src/main/java/com/macro/cloud/config/HttpExchangeConfig.java — HTTP client configuration for inter-service communication; shows modern Spring 6.0+ HttpExchange API usage replacing RestTemplate.
• admin-client/src/main/java/com/macro/cloud/service/impl/UserServiceImpl.java — Core business logic implementation demonstrating service-layer patterns and how microservices expose domain models in this architecture.
• authorization-server/src/main/java/com/macro/cloud/config/AuthorizationServerConfig.java — Spring Authorization Server (OAuth2/OIDC) configuration; critical for understanding the security layer and token generation across services.
• authorization-server/src/main/java/com/macro/cloud/controller/UserController.java — REST endpoint patterns and response handling; demonstrates CommonResult wrapper and error handling conventions used across all services.

Add a New REST Endpoint

1. Create or update a service interface in src/main/java/com/macro/cloud/service/ defining the business operation (admin-client/src/main/java/com/macro/cloud/service/UserService.java)
2. Implement the interface in src/main/java/com/macro/cloud/service/impl/ with @Service annotation (admin-client/src/main/java/com/macro/cloud/service/impl/UserServiceImpl.java)
3. Add a @RestController method in src/main/java/com/macro/cloud/controller/ returning CommonResult wrapper (admin-client/src/main/java/com/macro/cloud/controller/UserController.java)
4. Return response using CommonResult.success() or CommonResult.failed() to maintain consistent envelope format (admin-client/src/main/java/com/macro/cloud/domain/CommonResult.java)

Add a New Microservice

1. Create new module folder following pattern: modulename/pom.xml with parent reference to springcloud-learning-teach (admin-client/pom.xml)
2. Add Spring Cloud Alibaba Nacos Discovery dependency for automatic service registration (admin-client/pom.xml)
3. Create @SpringBootApplication main class in src/main/java/com/macro/cloud/ (admin-client/src/main/java/com/macro/cloud/AdminClientApplication.java)
4. Configure application-nacos.yml with service name, port, and Nacos server address (admin-client/src/main/resources/application-nacos.yml)
5. Create controllers, services, and domain models following the established patterns in admin-client (admin-client/src/main/java/com/macro/cloud/controller/UserController.java)

Configure Service-to-Service Communication

1. Create HttpExchangeConfig.java with @Configuration and @Bean methods for HTTP client setup (admin-client/src/main/java/com/macro/cloud/config/HttpExchangeConfig.java)
2. Define HTTP exchange interfaces with @HttpExchange annotations for target service endpoints (admin-client/src/main/java/com/macro/cloud/config/HttpExchangeConfig.java)
3. Inject RestClient or HttpServiceProxyFactory bean into services for type-safe inter-service calls (admin-client/src/main/java/com/macro/cloud/service/impl/UserServiceImpl.java)
4. Ensure both services are registered in Nacos for discovery; service name used in HTTP exchange URL (admin-client/src/main/resources/application-nacos.yml)

Add OAuth2/OIDC Protected Endpoints

1. Configure SecuritySecureConfig.java with SecurityFilterChain bean to define authorization rules (admin-security-server/src/main/java/com/macro/cloud/config/SecuritySecureConfig.java)
2. Add @EnableMethodSecurity for method-level @PreAuthorize annotations on controller methods (admin-security-server/src/main/java/com/macro/cloud/config/SecuritySecureConfig.java)
3. Implement RestAuthenticationEntryPoint for handling unauthenticated requests in REST APIs (authorization-server/src/main/java/com/macro/cloud/component/RestAuthenticationEntryPoint.java)
4. Reference AuthorizationServerConfig for token generation and scope validation setup (authorization-server/src/main/java/com/macro/cloud/config/AuthorizationServerConfig.java)

Nacos requirement: Services will fail silently if nacos.discovery.server-addr is unreachable; ensure Nacos server runs on localhost:8848 or update application-nacos.yml. JDK 17 minimum: Older Maven/IDE setups may default to JDK 8; explicitly set JAVA_HOME and pom.xml source/target to 17. Spring Boot 3 breaking changes: Old javax.* imports replaced with jakarta.* (already done here); third-party libs may not be compatible. Config precedence: application-nacos.yml requires active profile nacos (spring.profiles.active=nacos in application.yml or -Dspring.profiles.active=nacos at runtime), otherwise defaults to application.yml. HttpExchange vs RestTemplate: Code uses modern HttpExchange in HttpExchangeConfig.java; avoid mixing old RestTemplate patterns.

• Service Discovery (Nacos) — Core microservices pattern: automatic service registration and client-side/server-side discovery replaces hardcoded IPs; all modules depend on spring-cloud-starter-alibaba-nacos-discovery
• Centralized Configuration Management (Nacos Config) — Enables zero-downtime config updates across distributed services without redeployment; application-nacos.yml pattern shown here avoids environment-specific hardcoding
• Circuit Breaker Pattern (Sentinel) — Prevents cascading failures when downstream services timeout or fail; Spring Cloud Alibaba Sentinel is the fallback/rate-limiting implementation this repo teaches
• Distributed Transactions (Seata) — ACID guarantees across multiple microservices without distributed 2PC locks; mentioned in README as a taught component for handling cross-service consistency
• Spring Security CSRF Protection — CustomCsrfFilter in admin-security-server shows how to prevent cross-site request forgery in REST APIs; critical for web-facing microservices
• Container Orchestration (Kubernetes) — README promises k8s deployment chapters; understanding Pod/Service/Deployment abstractions is essential for running this microservices stack in production
• OpenFeign / HttpExchange — Declarative HTTP clients for inter-service communication; HttpExchangeConfig.java demonstrates Spring 6's modern HttpExchange bean, replacing RestTemplate and Feign

• macrozheng/mall-swarm — Parent project (11k+ stars): full e-commerce microservices system that this learning repo teaches from; reference for production patterns and complete feature examples
• alibaba/spring-cloud-alibaba — Official Nacos, Sentinel, Seata implementation; source of truth for Spring Cloud Alibaba component APIs and upgrade notes
• spring-projects/spring-cloud — Spring Cloud 2023 release line parent project; defines base architecture, LoadBalancer, Gateway, Stream that this repo teaches
• spring-projects/spring-boot — Spring Boot 3.2 base framework; source for Boot starters, Actuator health checks, and configuration precedence rules used throughout
• codecentric/spring-boot-admin — Admin UI server/client for monitoring services; admin-client depends on spring-boot-admin-starter-client for dashboard integration

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for admin-client UserService with Nacos discovery

The admin-client module has UserService and UserController but lacks integration tests that verify service discovery with Nacos and HTTP exchanges work correctly. Currently only AdminClientApplicationTests.java exists with no actual test methods. This is critical for a learning repo that teaches Spring Cloud Alibaba patterns.

• [ ] Add test cases in admin-client/src/test/java/com/macro/cloud/service/impl/UserServiceImplTest.java to test UserService methods
• [ ] Add integration tests in admin-client/src/test/java/com/macro/cloud/controller/UserControllerTest.java using MockMvc to test REST endpoints
• [ ] Add a test in AdminClientApplicationTests.java to verify Nacos service discovery initialization (check that service is registered)
• [ ] Configure test profile application-test.yml to use mock Nacos or embedded config

Add security tests for admin-security-server CustomCsrfFilter and SecuritySecureConfig

The admin-security-server has custom security configuration (SecuritySecureConfig.java, CustomCsrfFilter.java) but AdminSecurityServerApplicationTests.java is empty. Security configurations must be thoroughly tested, especially CSRF protection which is educational for learners. This prevents regressions in a teaching project.

• [ ] Create admin-security-server/src/test/java/com/macro/cloud/filter/CustomCsrfFilterTest.java with @WebMvcTest to test CSRF filter behavior
• [ ] Create admin-security-server/src/test/java/com/macro/cloud/config/SecuritySecureConfigTest.java to verify Spring Security configuration is applied
• [ ] Add test cases verifying CSRF token is required for POST/PUT/DELETE requests
• [ ] Add test cases verifying CSRF token validation with valid and invalid tokens

Add HttpExchangeConfig implementation tests and documentation

The admin-client has HttpExchangeConfig.java but it's likely using Spring 6+ HttpExchange feature (REST client alternative). Without tests, learners cannot understand how to properly configure and use this pattern. Add concrete tests showing the HTTP exchange configuration in action.

• [ ] Create admin-client/src/test/java/com/macro/cloud/config/HttpExchangeConfigTest.java to test HTTP exchange bean creation and configuration
• [ ] Add integration tests demonstrating HTTP exchanges calling remote services (e.g., calling another microservice endpoint)
• [ ] Add javadoc/comments in HttpExchangeConfig.java explaining the HttpExchange pattern vs RestTemplate/WebClient
• [ ] Create docs/HTTP_EXCHANGE_GUIDE.md explaining Spring 6 HttpExchange configuration with examples from this config

• Add integration tests for UserServiceImpl.java (admin-client/src/test/java/com/macro/cloud/ is empty except app test) that verify service→repository→controller flow and Nacos registration discovery
• Document Nacos configuration properties in a new docs/nacos-setup.md file: explain what each spring.cloud.nacos.* setting does and how to connect to Nacos server, then reference it from README.md's quick-start section
• Expand admin-security-server's SecuritySecureConfig.java with examples of role-based access control (RBAC) using Spring Security's @PreAuthorize and @Secured annotations on UserController endpoints (currently only has CSRF filter)

• High · Spring Boot Admin Client Without Authentication — admin-client/pom.xml, admin-client/src/main/resources/application.yml. The admin-client module includes spring-boot-admin-starter-client dependency without evidence of authentication configuration. Spring Boot Admin exposes sensitive application metrics and information that should be protected. Fix: Configure Spring Boot Admin authentication using spring.boot.admin.client.instance.metadata.user.name and user.password, or restrict access via network policies and Spring Security configuration.
• High · Actuator Endpoints Exposure — admin-client/pom.xml. The admin-client includes spring-boot-starter-actuator without visible endpoint security configuration. Actuator endpoints can expose sensitive application internals like environment variables, bean configurations, and health metrics. Fix: Configure actuator endpoint restrictions in application.yml: set management.endpoints.web.exposure.include to only necessary endpoints, disable sensitive endpoints like /env and /configprops, or require authentication.
• High · Potential CSRF Vulnerability in Security Module — admin-security-server/src/main/java/com/macro/cloud/filter/CustomCsrfFilter.java. The admin-security-server module contains a CustomCsrfFilter class. The implementation details are not visible, but custom CSRF filters are high-risk and may not properly protect against CSRF attacks if not implemented correctly. Fix: Review the CustomCsrfFilter implementation to ensure it follows OWASP CSRF protection standards. Consider using Spring Security's built-in CSRF protection instead of custom implementations.
• Medium · Missing Spring Security Configuration in Admin Client — admin-client/src/main/java/com/macro/cloud/controller/UserController.java. The admin-client module appears to lack explicit Spring Security configuration in the file structure. Without proper authentication and authorization, endpoints may be accessible to unauthorized users. Fix: Implement Spring Security configuration with proper authentication mechanisms (OAuth2, JWT, or Basic Auth) and authorization rules for all exposed endpoints.
• Medium · Nacos Configuration Without Security Details — admin-client/src/main/resources/application-nacos.yml, admin-server/src/main/resources/application-nacos.yml. The codebase uses Nacos for service discovery and potentially configuration management (application-nacos.yml files present). Nacos credentials and security configuration are not visible in the provided files. Fix: Ensure Nacos is configured with authentication enabled. Store credentials in environment variables or secure vaults, not in application configuration files. Enable TLS for Nacos communication.
• Medium · Authorization Server Without Visible Token Validation — authorization-server/src/main/java/com/macro/cloud/config/AuthorizationServerConfig.java. The authorization-server module is present but implementation details of token validation, expiration, and refresh mechanisms are not visible. This is critical for OAuth2/JWT implementations. Fix: Implement proper token validation with reasonable expiration times, refresh token rotation, and secure storage. Use industry-standard libraries (Spring Security OAuth2, Keycloak) rather than custom implementations.
• Medium · Potential Information Disclosure in Error Handlers — authorization-server/src/main/java/com/macro/cloud/component/RestAuthenticationEntryPoint.java, RestfulAccessDeniedHandler.java. RestAuthenticationEntryPoint and RestfulAccessDeniedHandler are present in authorization-server but their implementation is not visible. Custom error handlers may leak sensitive information. Fix: Ensure error responses do not leak stack traces, system information, or internal paths. Return generic error messages to clients while logging detailed information server-side.
• Medium · Hutool Dependency Version Not Pinned — admin-client/pom.xml. The hutool-all dependency uses a variable version (${hutool-version}) which may lead to inconsistent builds and potential security issues if older versions are used. Fix: Explicitly pin hutool-all to a specific secure version in the parent pom.xml. Regularly update and monitor for security advisories.
• Low · Microservices Without Visible API Gateway Protection — undefined. Multiple microservices (admin-client, authorization-server Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.