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)