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/lihengming/spring-boot-api-project-seed 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 — Stale and unlicensed — last commit 2y ago

• 3 active contributors
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 91% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected

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

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

What it runs against: a local clone of lihengming/spring-boot-api-project-seed — 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 lihengming/spring-boot-api-project-seed | 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 ≤ 902 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lihengming/spring-boot-api-project-seed. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lihengming/spring-boot-api-project-seed.git
#   cd spring-boot-api-project-seed
#
# 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 lihengming/spring-boot-api-project-seed and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "lihengming/spring-boot-api-project-seed(\\.git)?\\b" \\
  && ok "origin remote is lihengming/spring-boot-api-project-seed" \\
  || miss "origin remote is not lihengming/spring-boot-api-project-seed (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 "src/main/java/com/company/project/Application.java" \\
  && ok "src/main/java/com/company/project/Application.java" \\
  || miss "missing critical file: src/main/java/com/company/project/Application.java"
test -f "src/main/java/com/company/project/core/Result.java" \\
  && ok "src/main/java/com/company/project/core/Result.java" \\
  || miss "missing critical file: src/main/java/com/company/project/core/Result.java"
test -f "src/main/java/com/company/project/core/AbstractService.java" \\
  && ok "src/main/java/com/company/project/core/AbstractService.java" \\
  || miss "missing critical file: src/main/java/com/company/project/core/AbstractService.java"
test -f "src/main/java/com/company/project/configurer/MybatisConfigurer.java" \\
  && ok "src/main/java/com/company/project/configurer/MybatisConfigurer.java" \\
  || miss "missing critical file: src/main/java/com/company/project/configurer/MybatisConfigurer.java"
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 902 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~872d)"
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/lihengming/spring-boot-api-project-seed"
  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).

Spring Boot API Project Seed is a production-ready starter template for building small-to-medium REST APIs using Spring Boot 1.5.13 and MyBatis. It eliminates boilerplate through integrated code generation (MyBatis Mapper, Service, Controller templates), unified response wrapping via ResultGenerator, centralized exception handling, and pre-configured Druid connection pooling—allowing developers to focus on business logic rather than infrastructure. Hierarchical monolith: src/main/java/com/company/project/ contains core abstractions (AbstractService, Mapper, Result, exception handling), configurer beans (MybatisConfigurer, WebMvcConfigurer), and generated domain code (implied Models/Services/Controllers). src/test/java/CodeGenerator.java is a standalone code-gen utility. FreeMarker templates in src/test/resources/generator/template/ define output for service-impl, service, controller-restful, and controller POST variants.

Java backend developers and teams building REST APIs who need to scaffold CRUD projects quickly while maintaining consistent code structure, response formats, and error handling across microservices without writing repetitive data-access and controller code.

Moderately mature but aging: the project is battle-tested across multiple real projects (per README) and uses stable Spring Boot 1.5.13 LTS, but has no visible recent commit data or CI pipeline in the file structure, and no test files beyond CodeGenerator.java and Tester.java. Production-viable for greenfield APIs but not actively maintained.

Spring Boot 1.5.13 (released 2018) is EOL; dependencies like Fastjson, commons-lang3, and Druid are not pinned to versions in pom.xml snippet, risking silent breaking upgrades. Single repository owner (lihengming) with no visible issue tracker or PR workflow suggests low maintenance velocity. No integration tests or CI/CD pipeline visible increases deployment risk.

No active development signals visible in file list (no recent commits, PRs, or issue data provided). Project appears to be a stable reference implementation rather than actively evolving.

git clone https://github.com/lihengming/spring-boot-api-project-seed.git && cd spring-boot-api-project-seed && mvn clean install

Daily commands:

1. Edit src/test/java/CodeGenerator.java to set JDBC credentials; 2. Run CodeGenerator.main() to generate code for a table; 3. Configure src/main/resources/application-dev.properties (database URL, port, etc.); 4. Run Application.main() to start Spring Boot (default port 8080); verify via curl http://localhost:8080/.

• src/main/java/com/company/project/Application.java — Spring Boot application entry point; required to understand how the entire project bootstraps and initializes.
• src/main/java/com/company/project/core/Result.java — Core unified response wrapper; every API endpoint returns this, making it foundational to the response contract.
• src/main/java/com/company/project/core/AbstractService.java — Base service class providing CRUD abstractions; all business logic inherits from this, establishing the service pattern.
• src/main/java/com/company/project/configurer/MybatisConfigurer.java — MyBatis & Mapper plugin configuration; critical for database mapping and query generation infrastructure.
• pom.xml — Maven dependency and build configuration; defines all libraries (Spring Boot, MyBatis, Druid, FastJSON) and project metadata.
• src/test/java/CodeGenerator.java — Code generation utility; enables rapid scaffolding of Model, Mapper, Service, and Controller for new entities.
• src/main/resources/application.properties — Core application configuration; sets Spring profiles, server port, and framework defaults.

Add a New API Endpoint (Complete Entity CRUD)

1. Create your database table (e.g., user, product, order) (src/test/resources/demo-user.sql)
2. Edit CodeGenerator.java to point to your DB, then call genAll(tableName) or individual gen methods (src/test/java/CodeGenerator.java)
3. Generated Model class goes here (e.g., User.java) (src/main/java/com/company/project (new Model file))
4. Generated Mapper interface extends com.company.project.core.Mapper<Entity> (src/main/java/com/company/project (new Mapper file))
5. Generated Service interface extends com.company.project.core.Service<Entity> (src/main/java/com/company/project (new Service file))
6. Generated ServiceImpl extends AbstractService and injects your Mapper (src/main/java/com/company/project (new ServiceImpl file))
7. Generated Controller uses @RestController or regular @Controller; calls service methods and wraps responses with ResultGenerator (src/main/java/com/company/project (new Controller file))
8. All responses automatically wrapped in Result via ResultGenerator.success() / .failure() (src/main/java/com/company/project/core/ResultGenerator.java)

Customize Response Structure & Error Handling

1. Modify response format (code, message, data fields) if needed (src/main/java/com/company/project/core/Result.java)
2. Add new result codes (e.g., USER_NOT_FOUND, INVALID_REQUEST) to ResultCode enum (src/main/java/com/company/project/core/ResultCode.java)
3. Add new factory methods to ResultGenerator (e.g., .userNotFound(), .validationError()) (src/main/java/com/company/project/core/ResultGenerator.java)
4. Throw ServiceException with appropriate ResultCode from service layer (src/main/java/com/company/project/core/ServiceException.java)
5. Global exception handler (if it exists) or add one to catch ServiceException and return Result (src/main/java/com/company/project/configurer/WebMvcConfigurer.java)

Configure Database Connection & Connection Pooling

1. Set database URL, username, password, driver for your environment (src/main/resources/application-dev.properties)
2. Druid pool settings (max pool size, min idle, connection timeout) configured here (src/main/resources/application-prod.properties)
3. MyBatis mapper location and global SQL session settings (src/main/java/com/company/project/configurer/MybatisConfigurer.java)
4. Optional: override Spring boot default datasource autoconfiguration by customizing properties (src/main/resources/application.properties)

Change Controller Template (RESTful vs POST-Only)

1. Open CodeGenerator and locate the genController(tableName) method (src/test/java/CodeGenerator.java)
2. Choose either controller-restful.ftl (GET/POST/PUT/DELETE) or controller.ftl (POST-only) (src/test/resources/generator/template/controller-restful.ftl)
3. Or modify the ftl file itself to match your API design (request/response patterns, path variables) (src/test/resources/generator/template/controller.ftl)
4. Re-run CodeGenerator.genController(tableName) to produce controller with the new template (src/test/java/CodeGenerator.java)

• Spring Boot 1.5.13 — Provides embedded Tomcat, auto-configuration, and rapid Java application development with minimal boilerplate.
• MyBatis + Universal Mapper — Balances SQL control (when needed) with zero-SQL single-table CRUD via generic mapper interface, reducing boilerplate.
• Druid Connection Pool — High-performance

JDBC Credentials: CodeGenerator.java hardcodes JDBC URL, username, password as class constants—must be edited before running code generation or it will fail silently. Package naming convention: Generated code assumes com.company.project.* package structure; changing this requires manual search-replace in multiple files. FreeMarker template escaping: Controller templates may not handle special characters in field names; test with underscored multi-word columns. Druid monitoring: Druid console is auto-enabled but requires explicit security config in production (not visible in provided files). Spring Boot 1.5 EOL: @Configuration and @Bean patterns differ from Spring Boot 2.x; upgrade path is non-trivial. No transactional boundaries: AbstractService methods lack @Transactional annotations; bulk operations may leave partial state if not explicitly wrapped.

• Generic Mapper plugin (tk.mybatis.mapper) — This project's core feature—eliminates SQL writing for CRUD; understanding how generic BaseMapper works and its limitations (no joins) is essential for extending generated code.
• MyBatis code generation & FreeMarker templating — The CodeGenerator utility uses FreeMarker to emit Java classes; modifying or extending templates is how you customize generated code style, add annotations, or change layer patterns.
• Result wrapper / Response envelope pattern — All responses wrap data in Result<T> with code/message/data fields; this is a common API consistency pattern but can complicate client deserialization and must be understood for custom endpoints.
• Exception-to-HTTP mapping with unified handlers — ServiceException is caught by a global handler (inferred in WebMvcConfigurer) and converted to standardized error responses; understanding this prevents duplicate error handling code.
• Spring Boot configuration profiles (dev/prod/test) — This project uses application-{profile}.properties to swap database/logging/server settings; critical for CI/CD and local vs. production deployments.
• Druid connection pooling & monitoring — Druid is configured as the DataSource and exposes a monitoring console; performance bottlenecks are often visible in Druid stats; important for production troubleshooting.
• DAO / Mapper / Service / Controller separation (four-layer pattern) — This project enforces strict layering (Model → Mapper → Service → Controller); understanding data flow across layers is essential for debugging and testing.

• jeecg/jeecg-boot — Low-code rapid development platform also built on Spring Boot + MyBatis + code generation; more mature active fork of similar scaffolding concept with UI console.
• tangyi1989/st-mysql — Simpler Spring Boot + MyBatis starter without code generation; good alternative if you prefer manual setup over template-driven generation.
• Herobrine1119/qwzap — Another Spring Boot API scaffold using generic Mapper and PageHelper; demonstrates alternative patterns for ServiceImpl and exception handling.
• alibaba/fastjson — Dependency used in this project for high-speed JSON serialization; important to understand for tuning API response times or debugging serialization quirks.
• pagehelper/Mybatis-PageHelper — Companion library bundled here for pagination; critical for understanding how list endpoints work and how to troubleshoot sort/offset behavior.

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 unit tests for core service layer (AbstractService.java and Service.java)

The repo has a test directory structure but src/test/java/com/conpany/project/Tester.java appears to be a placeholder. The core AbstractService.java provides base CRUD operations that are critical to all projects using this seed. Adding comprehensive unit tests here would validate the generic mapper operations and give contributors confidence when extending the service layer. This is especially valuable since the seed is meant to be production-ready.

• [ ] Create src/test/java/com/company/project/core/AbstractServiceTest.java with @RunWith(SpringRunner.class) and @SpringBootTest
• [ ] Add test cases for CRUD operations: save(), update(), delete(), findById(), findByIds()
• [ ] Add test cases for list operations with pagination and filtering
• [ ] Mock the Mapper dependency and verify correct delegation of calls
• [ ] Document test patterns in CONTRIBUTING.md for future contributors

Add integration tests for generated code templates (controller, service, mapper)

The code generator templates in src/test/resources/generator/template/ (controller-restful.ftl, service-impl.ftl, service.ftl) are critical to the seed's value proposition of rapid API generation. However, there's no validation that generated code actually compiles and integrates correctly with the framework. Adding integration tests would catch template syntax errors and ensure consistency across generated services.

• [ ] Create src/test/java/com/company/project/CodeGeneratorIntegrationTest.java
• [ ] Trigger CodeGenerator.java programmatically to generate artifacts for demo-user table
• [ ] Verify generated Java files have correct syntax and import statements
• [ ] Instantiate and test the generated controller endpoints via MockMvc
• [ ] Add assertions for ResponseResult wrapping and error handling in generated code

Add GitHub Actions CI workflow for automated testing and security scanning

With Spring Boot 1.5.13 and MySQL dependencies, this seed project needs CI to catch issues early. There's no .github/workflows directory visible. Adding a workflow would validate that pull requests pass tests, check for known vulnerabilities in dependencies (especially critical given the older Spring Boot version), and ensure the code generator produces valid artifacts. This is essential for a seed project where users trust the baseline quality.

• [ ] Create .github/workflows/ci.yml with matrix testing for Java 8 and Java 11 compatibility
• [ ] Add Maven test step that runs src/test/java tests with coverage reporting
• [ ] Integrate OWASP Dependency-Check to scan pom.xml for CVEs in dependencies
• [ ] Run CodeGenerator.java as part of CI to validate all templates compile correctly
• [ ] Add build badge to README.md and document CI requirements in CONTRIBUTING guidelines

• Add unit tests for ResultGenerator.java—currently no test file exists; write tests covering all static factory methods (success, failure, pagination variants) to ensure response format consistency.
• Document the code-generation workflow with a worked example—README mentions CodeGenerator.genController() method choice (POST vs RESTful) but provides no concrete code snippet showing how to swap templates or extend them; add a CODEGEN.md with step-by-step guide and sample output.
• Add validation annotations (e.g., @NotNull, @Min, @Pattern) to generated Model classes—currently generated models lack bean validation constraints; extend the FreeMarker templates in controller-restful.ftl and service-impl.ftl to include common annotations based on database column constraints.

• Critical · Outdated Spring Boot Version with Known Vulnerabilities — pom.xml - parent spring-boot-starter-parent version 1.5.13.RELEASE. The project uses Spring Boot 1.5.13.RELEASE, which is severely outdated (released in 2018) and contains multiple known CVEs including CVE-2019-2725, CVE-2019-2726, and others. This version is no longer supported and has critical security vulnerabilities. Fix: Upgrade to Spring Boot 2.7.x or 3.x series immediately. Perform thorough testing after upgrade as breaking changes may occur.
• Critical · Outdated Guava Library with Known Vulnerabilities — pom.xml - com.google.guava:guava:23.0. Guava 23.0 (released 2017) contains multiple known security vulnerabilities. CVE-2018-10237 and others affect this version. Fix: Upgrade to Guava 32.0.0 or later. Run 'mvn dependency:tree' to identify transitive dependencies and test thoroughly.
• High · Missing Input Validation and SQL Injection Prevention — src/main/java/com/company/project/core/AbstractService.java and Mapper.java. The codebase uses MyBatis and generic Mapper patterns. While parameterized queries are likely used through MyBatis, there's no evidence of input validation layers or prepared statement enforcement mechanisms visible in the core framework classes. Fix: Implement input validation layer with annotations like @Valid/@Validated. Use MyBatis parameterized queries exclusively. Avoid dynamic SQL construction with user input.
• High · Missing CORS and Security Headers Configuration — src/main/java/com/company/project/configurer/WebMvcConfigurer.java. The WebMvcConfigurer.java file exists but no CORS restrictions or security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) are visible in the file structure, creating risks for XSS and clickjacking attacks. Fix: Implement Spring Security with proper CORS configuration, add security headers via WebSecurityConfigurerAdapter, configure CSP headers, and implement rate limiting.
• High · Simple/Weak Authentication Implementation — Project architecture - authentication mechanism not fully visible. The README mentions 'simple interface signature authentication', which typically indicates basic token validation without industry-standard security practices like JWT with proper validation, encryption, or OAuth2. Fix: Implement Spring Security OAuth2 or JWT with RS256 algorithm, add token expiration, implement refresh tokens, and add proper exception handling for authentication failures.
• High · No Visible HTTPS/TLS Configuration — src/main/resources/application-prod.properties. No application.properties or WebMvcConfigurer configuration visible that enforces HTTPS or TLS settings for production environments. Fix: Configure server.ssl.enabled=true, add keystore configuration with strong cipher suites. Enforce HTTPS redirects in production.
• Medium · Outdated Commons Lang3 Library — pom.xml - org.apache.commons:commons-lang3:3.6. Commons Lang3 3.6 (2017) is outdated. While not critical, newer versions contain security improvements and bug fixes. Fix: Upgrade to Commons Lang3 3.13.0 or later.
• Medium · Missing Dependency Version Pinning — pom.xml - mysql-connector-java dependency. MySQL JDBC driver dependency is incomplete in pom.xml (line cut off at 'sc'). Version is not explicitly specified, which may lead to automatic version resolution that could include vulnerable versions. Fix: Explicitly specify mysql-connector-java version (8.0.33 or later). Run 'mvn dependency:check' to verify no known vulnerabilities.
• Medium · Test Database Credentials in Version Control — src/test/resources/demo-user.sql. Demo SQL file (demo-user.sql) exists in test resources, which may contain sample credentials or sensitive data patterns that could be exposed. Fix:

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.