houtu-dependencies

houtu-dependencies enterprise-grade Spring Cloud microservice foundational framework complete usage guide. GroupId is io.github.lujiafa, covering unified response, exception handling, parameter parsin

SKILL.md

GitHub

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):

Coding Task Module Reference File
New microservice / First-time setup — references/quick-start.md
Write Controller / Unified response / Exception handling / Parameter binding houtu-web references/module-web.md
Auth / Permissions / Session / Signing / Anti-replay houtu-web-security references/module-security.md
Distributed lock / Rate limiting houtu-cache references/module-cache-lock.md
Database field encryption houtu-data-security references/module-data-security.md
Request access logging houtu-access-log references/module-access-log.md
Canary routing / Feign / Sentinel / Service discovery spring-cloud-houtu-* references/module-cloud.md
Config value decryption houtu-core references/module-config-decrypt.md
API documentation houtu-web-swagger references/module-swagger.md
Crypto / Signing / Hash / JSON / HTTP client utilities houtu-utils references/module-utils.md
Monitoring / Metrics / Observability houtu-actuator references/module-actuator.md
Async / Scheduled tasks / Cross-thread context propagation houtu-core references/module-concurrent.md

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 Characteristic Framework Capability to Enhance Description
Any Controller method ResponseData<T> + BaseForm/PageForm Basic convention; all endpoints must follow
Requires login to access @CheckSession Add by default for user-related endpoints
Role-based permissions (e.g., admin vs. regular user) @RequiresRole / @RequiresPermission Determine from business description; no need for user to specify each one
Endpoint has audit/traceability requirements @AccessLog Proactively add for financial, order, or sensitive operations
Endpoint receives user-input rich text/comments @NotXss Should be added to all user-editable text fields
List query (with pagination) PageForm + PageDataVO<T> Apply when "list", "query", "pagination" intent is identified

Business Layer (Service)

Business Characteristic Framework Capability to Enhance Description
Concurrent write operations (e.g., placing orders, deducting inventory, deducting balance) @Lock Proactively add when concurrency-sensitive operations like "payment", "inventory", "balance" are identified
Submission operations (e.g., placing orders, payments, transfers) @CheckRepeatRequest Proactively add for write operations with idempotency requirements
Calling external HTTP APIs (e.g., payment callbacks, third-party integrations) HttpClients Do not use RestTemplate/WebClient
Object conversion (Entity → VO / Form → DTO) BeanUtils.smartCopyProperties Do not use Spring BeanUtils
JSON operations JsonUtils Do not create your own ObjectMapper
High-concurrency hotspot operations (e.g., flash sales) RateLimiter Apply when "rate limiting", "flash sale", "rush purchase" intent is identified
Async/scheduled tasks needing session or context access Framework auto-propagation (TransferThreadPoolTaskExecutor) @Async, @Scheduled, CompletableFuture automatically inherit parent thread's SessionContext, HintContext, etc.; no manual handling needed

Data Layer

Business Characteristic Framework Capability to Enhance Description
Storing sensitive fields like phone numbers, ID cards, bank accounts @SecurityWatch + @SecurityParam Proactively suggest when field names contain phone/mobile/idCard/bankAccount, etc.
Database passwords, API Keys in config files houtu-core config decryption Proactively suggest when password, secret, key config items are identified

Microservice Layer

Business Characteristic Framework Capability to Enhance Description
Inter-service calls @AutoFeign Do not hand-write FeignClient + RequestInterceptor
Canary/AB testing/multi-tenant routing HintContext Apply when "canary", "canary release", "route specific users" intent is identified
External system callbacks (e.g., payment notifications) @CheckSign + @CheckRepeatRequest Callback scenarios typically require both signature verification and anti-replay

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)

Scenario ⚠️ Avoid by Default ✅ Framework Approach (Preferred)
Endpoint auth Import spring-security or hand-write Filter to verify token @CheckSession + @RequiresRole / @RequiresPermission
Unified response Custom Result/Response class or wrap with ResponseEntity Return ResponseData<T> or EmbedResponseData
Exception handling Hand-write @ControllerAdvice + @ExceptionHandler Throw BusinessException; framework handles automatically
Parameter validation response Manually catch BindException and format Framework handles automatically, returns {code:30, message:"..."}
Database field encryption Hand-write TypeHandler or manually encrypt/decrypt in Service layer @SecurityWatch + @SecurityParam annotations
Distributed lock Hand-write Redis SETNX or Redisson calls @Lock annotation or LockSupport
Feign calls Hand-write RequestInterceptor to pass headers Framework auto-propagates; use @AutoFeign to publish interfaces
Request logging Hand-write Filter/Interceptor to record logs @AccessLog annotation
Signature verification Hand-write signature verification interceptor @CheckSign annotation
Anti-replay Hand-write Redis idempotency check @CheckRepeatRequest annotation
Load balancing Hand-write LoadBalancer strategy Use HintContext + configure weights
Swagger docs Manually import springdoc/springfox and configure Import houtu-web-swagger starter
Rate limiting Hand-write Redis Lua rate limiting script Use RateLimiter
Symmetric/asymmetric encryption Manually import BouncyCastle or hand-write crypto utility classes Use SM4Utils / AESUtils / RSAUtils / SM2Utils, etc.
JSON serialization Manually create ObjectMapper instances Use JsonUtils
HTTP client Manually create RestTemplate or HttpClient Use framework's auto-configured HttpClients
Config value decryption Hand-write EnvironmentPostProcessor or manually decrypt at startup Use houtu-core's decrypt configuration
Monitoring metrics Hand-write Micrometer MeterBinder to collect endpoint metrics Import houtu-actuator starter for automatic collection
Async thread context propagation Hand-write TaskDecorator or manually set/get context in child threads Framework auto-replaces with TransferThreadPoolTaskExecutor; @Async/CompletableFuture/@Scheduled auto-propagate SessionContext, HintContext, etc.

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

Annotation Target Module Key Parameters
@CheckSession TYPE, METHOD houtu-web-security value(bool, default true)
@RequiresRole METHOD houtu-web-security value(String[]), logic(Logic.OR/AND, default OR)
@RequiresPermission METHOD houtu-web-security value(String[]), logic(Logic.OR/AND, default OR)
@CheckSign TYPE, METHOD houtu-web-security value(bool, default true)
@CheckRepeatRequest TYPE, METHOD houtu-web-security (no parameters)
@Lock METHOD houtu-cache prefix(String), key(String), leaseTime(long, -1), waitTime(long, -1), unit(TimeUnit.SECONDS)
@AccessLog TYPE, METHOD houtu-access-log value(bool), requestHeaders(String[], default USER_AGENT), requestBody(bool, default false), logFilterHandler(Class)
@SecurityWatch TYPE, METHOD houtu-data-security encrypt(bool), encryptMapKeys(String[]), decrypt(bool), decryptMapKeys(String[]), processorBeanName(String), processorClass(Class)
@SecurityParam PARAMETER, FIELD houtu-data-security (no parameters)
@AutoFeign TYPE, METHOD sc-houtu-feign value(bool, default true), responseBody(bool, default true)
@NotXss FIELD, PARAMETER houtu-web message(String, default "内容包含不安全信息")

Predefined Error Codes (ErrorCodeConstant)

Code Constant Description
0 SUCCESS Success
1 INTERNAL_ERROR Internal error
2 SERVER_BUSY Server busy
3 NETWORK_ERROR Network error
4 OPERATION_FAIL Operation failed
5 REQUEST_INVALID Invalid request
6 REQUEST_INVALID_IP Invalid IP
7 REQUEST_INVALID_DATA Invalid data
8 REQUEST_REPEAT Duplicate request
9 REQUEST_TOO_FREQUENCY Request too frequent
10 USERNAME_NOT_EXIST Username does not exist
11 ACCOUNT_LOCKED Account locked
12 ACCOUNT_EXCEPTION Account exception
13 PASSWORD_ERROR Password error
14 USERNAME_OR_PASSWORD_ERROR Username or password error
15 SESSION_EXPIRED Session expired
16 SESSION_KICK_OUT_EXPIRED Session kicked out
17 INVALID_VERIFICATION_INFO Invalid verification info
18 INVALID_SIGNATURE_INFO Invalid signature
19 ACCESS_PERMISSIONS_DENIED Access denied
30 PARAMETER_ERROR Parameter error
31 PARAMETER_FORMAT_ERROR Parameter format error
32 NOT_SUPPORTED_PARAMETER_TYPE_CONVERSION Parameter type conversion not supported
40 DATA_LOADING_FAILED Data loading failed
41 DATA_NOT_EXIST Data does not exist
42 DATA_ALREADY_EXIST Data already exists (in v2.7.1, v3.5.0, v3.5.1 this was 41, same as DATA_NOT_EXIST — a bug fixed in v2.7.2+ and v3.5.2)

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>
Module Key Source Files (under src/main/java/)
houtu-core .../core/exception/BusinessException.java, .../core/exception/ErrorCode.java, .../core/constant/ErrorCodeConstant.java, .../core/context/SpringApplicationContext.java
houtu-web .../web/model/ResponseData.java, .../web/model/EmbedResponseData.java, .../web/model/vo/PageDataVO.java, .../web/model/form/PageForm.java, .../web/handler/UnifiedHandlerExceptionResolver.java, .../web/validation/constroins/NotXss.java
houtu-web-security .../websecurity/annotation/*.java, .../websecurity/session/SessionContext.java
houtu-cache .../lock/annotation/Lock.java, .../lock/support/LockSupport.java, .../lock/support/BLock.java, .../limit/RateLimiter.java
houtu-data-security .../data/security/annotation/SecurityWatch.java, .../data/security/handler/SecurityProcessor.java
houtu-access-log .../accesslog/annotation/AccessLog.java, .../accesslog/handler/LogFilterHandler.java
houtu-utils .../util/crypto/*.java, .../util/JsonUtils.java, .../util/HttpClients.java
houtu-actuator .../actuator/metrics/*.java
sc-houtu-loadbalancer .../loadbalancer/support/hint/HintContext.java
sc-houtu-feign .../feign/anotation/AutoFeign.java
sc-houtu-discovery .../discovery/context/ServiceContext.java

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

Feature v3.5.2 v3.5.1 v3.5.0 v2.7.3 v2.7.2 v2.7.1
JDK 17+ 17+ 17+ 1.8+ 1.8+ 1.8+
Spring Boot 3.5.11 3.5.11 3.5.11 2.7.18 2.7.18 2.7.18
Package prefix io.github.lujiafa.houtu Same Same Same Same Same
Namespace jakarta.* jakarta.* jakarta.* javax.* javax.* javax.*
Redis config spring.data.redis.* Same Same spring.redis.* spring.redis.* spring.redis.*
Nacos config spring.config.import Same bootstrap.yml bootstrap.yml bootstrap.yml bootstrap.yml
SCA version 2025.0.0.0 Same 2023.0.1.2 2021.0.6.2 2021.0.6.2 2021.0.6.2
@Lock SpEL ✅ ✗ ✗ ✅ ✗ ✗

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