Houtu Dependencies

Houtu Framework — AI Agent Coding Guide

houtu-dependencies is an enterprise-grade foundational framework for Spring Boot / Spring Cloud microservices that implements "Activate-on-import" via the Spring Boot Starter mechanism, allowing developers to focus entirely on business logic.

Repository: https://github.com/lujiafa/houtu-dependencies Git Branches: 3.5.2, 3.5.1, 3.5.0, 2.7.3, 2.7.2, 2.7.1 (branch name = version)

Core Principles

1. Activate-on-import — Capabilities are automatically enabled after adding a starter dependency; no @Enable annotations or manual configuration needed
2. Annotation-driven — Control behavior through annotations (@Lock, @CheckSession, @SecurityWatch...); do not hand-write interceptors/AOP
3. Framework-first — For capabilities already encapsulated by the framework, use the framework approach by default instead of native Spring; defer to user when they explicitly request the native approach
4. Convention over configuration — Follow framework defaults; only override when customization is needed
5. Version-aware — Package paths, API names, and configuration approaches differ across versions; the version must be confirmed before generating code

Code Generation Workflow (must be executed in order)

Step 1: Detect Version & Dependencies → Step 2: Identify Scenario → Step 3: Load Module Reference → Step 4: Generate Code → Step 5: Verify

Step 1 — Detect Version & Dependencies

The version must be determined before generating any code, and the BOM must be imported.

Read the project build file (pom.xml or build.gradle / build.gradle.kts) and determine in the following order:

1a. houtu already imported — The build file contains houtu-dependencies or spring-cloud-houtu:

• Read the version number directly to determine the version, proceed to Step 2
• Multi-module projects: The BOM is usually declared in the root pom.xml or root build.gradle under dependencyManagement; submodules inherit it and do not need to add it again

1b. Not imported but user explicitly wants houtu — The user mentions "use houtu", "integrate houtu", "use houtu-dependencies", etc.:

• Confirm the version (ask the user or infer from the project's Spring Boot version: 3.x → 3.5.2, 2.x → 2.7.3)

• Proactively add the BOM to the build file:

  Maven (pom.xml):

  <!-- Base module BOM (required) -->
  <dependency>
      <groupId>io.github.lujiafa</groupId>
      <artifactId>houtu-dependencies</artifactId>
      <version>${version}</version>
      <type>pom</type>
      <scope>import</scope>
  </dependency>
  

  Gradle (build.gradle / build.gradle.kts):

  // Base module BOM (required)
  implementation platform("io.github.lujiafa:houtu-dependencies:${version}")
  

  If the task involves Spring Cloud modules (Feign, canary routing, Sentinel, service discovery), also add:

  <!-- Maven: Spring Cloud enhancement module BOM -->
  <dependency>
      <groupId>io.github.lujiafa</groupId>
      <artifactId>spring-cloud-houtu</artifactId>
      <version>${version}</version>
      <type>pom</type>
      <scope>import</scope>
  </dependency>
  

  // Gradle: Spring Cloud enhancement module BOM
  implementation platform("io.github.lujiafa:spring-cloud-houtu:${version}")
  

• Load references/quick-start.md to complete first-time setup

1c. Cannot determine — Ask the user, or default to the latest version 3.5.2

After determining the version, immediately load the corresponding version reference file (references/v{version}.md) to obtain:

• The correct package prefix (io.github.lujiafa.houtu.*)
• The correct namespace (jakarta.* or javax.*)
• The correct configuration path (spring.data.redis.* or spring.redis.*)
• Dependency versions (Spring Boot, Spring Cloud, Redisson, etc.)

Step 2 — Identify Scenario & Select Module

Analyze the coding task — not only match the user's explicit requirements, but also proactively identify scenarios that can be enhanced based on business logic semantics (see the "Business Scenario Enhancement Guide" below).

Select the module reference files to load from the table below (a single task usually involves multiple modules):

Example: When the user says "write a payment endpoint", you should simultaneously identify: houtu-web (Controller response) + houtu-web-security (login authentication) + houtu-cache (@Lock for concurrency protection + @CheckRepeatRequest for anti-replay) + houtu-access-log (audit logging for financial operations), rather than just writing a bare Controller.

Step 3 — Load Module Reference Files

Load the corresponding module reference files before writing code. Each file is a complete recipe: Maven dependency → Required configuration → import → Code patterns → Practices to avoid by default → Internal behavior.

If the task involves multiple modules, load all relevant files.

Step 4 — Generate Code (with automatic dependency management)

1. Check and add missing Starter dependencies — Check whether the modules required for the current scenario are already imported in the <dependencies> of pom.xml; if not, proactively add them (no version needed, managed by BOM). Similarly, if the scenario involves spring-cloud-houtu-* modules, ensure the spring-cloud-houtu BOM is already in <dependencyManagement>
2. Use the correct package prefix and imports from the version file
3. Use the API patterns and code examples from the module files
4. Check the Anti-Pattern Checklist — Confirm that native Spring approaches are not used to duplicate functionality
5. Use the framework's Model base classes (BaseForm, BaseVO, BaseDTO, PageForm, PageDataVO, etc.)

Step 5 — Verify

For uncertain APIs, verify by reading source code via git show <branch>:<path>:

git show <branch>:<file-path>
# Example:
git show 3.5.2:houtu-cache/src/main/java/io/github/lujiafa/houtu/lock/annotation/Lock.java

Business Scenario Enhancement Guide (Proactively identify, apply when appropriate)

When writing business code, do not wait for the user to explicitly specify framework features; instead, proactively identify applicable framework capabilities based on the semantics of the business logic and naturally integrate them into the code. Below are common business scenarios and their mapping to framework enhancements:

Interface Layer (Controller)

Business Layer (Service)

Data Layer

Microservice Layer

Application Principles

1. Do not over-enhance — Only apply when business semantics truly match; do not pile on annotations just to showcase features. For example, internal admin tools may not need @AccessLog; simple queries do not need @Lock
2. Do not miss critical enhancements — Scenarios involving finance, security, or concurrency must have corresponding capabilities applied; this is the core value of the framework
3. Progressive adoption — When users first integrate, ensure basic capabilities (houtu-web) first; then gradually introduce other modules based on actual scenarios in subsequent coding
4. Add dependencies on demand — When using a module's capabilities, first check whether the Starter is already imported in pom.xml; if not, proactively add it

Anti-Pattern Checklist (Agent follows by default during autonomous coding; defers to user when explicitly requested)

Model Base Class Hierarchy

Business code should inherit from the framework-provided base classes:

BaseResponseData<T>        (interface: getCode(), getMessage(), getData())
├── ResponseData<T>        (standard JSON response with code/message/data)
└── EmbedResponseData      (extends LinkedHashMap, flattened response)

BaseForm                   (request form base class, implements Serializable)
└── PageForm               (pagination request, contains currentPage/pageSize)

BaseDTO                    (data transfer base class, implements Serializable)
├── PageQueryDTO           (pagination query DTO, contains currentPage/pageSize)
└── PageDataDTO<R,V>       (pagination data DTO, contains records/totalRecords/totalPages)

BaseVO                     (view object base class, implements Serializable)

PageDataVO<V> extends BaseDTO  (pagination response, contains records/totalRecords/totalPages/currentPage/pageSize)
└── PageDataExtVO<D,V>         (pagination response + extra data field D data, e.g., paginated list with summary statistics)

PageDataVO static factory methods:

• PageDataVO.build(PageDataDTO dto, Class<V> clazz) — Convert from DTO
• PageDataVO.build(currentPage, pageSize, totalRecords, List<V> records) — Build manually
• PageDataVO.empty() — Empty pagination

Annotation Quick Reference

Predefined Error Codes (ErrorCodeConstant)

Custom business error codes should start from 100, built via ErrorCode.build(code), with i18n support.

Source Code Verification (Fallback)

When reference files do not cover a specific API or you need to confirm parameters, read framework source code via git show:

git show <branch>:<file-path>

Path prefix: io/github/lujiafa/houtu Note: The package name for @AutoFeign is anotation (not annotation); this is the framework's original spelling.

Version Quick Comparison

See version details at references/v{version}.md