# Houtu Dependencies

> >

- **Type:** Skill
- **Install:** `agentstack add skill-lujiafa-houtu-project-skills-houtu-dependencies`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lujiafa](https://agentstack.voostack.com/s/lujiafa)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lujiafa](https://github.com/lujiafa)
- **Source:** https://github.com/lujiafa/houtu-project-skills/tree/main/skills/houtu-dependencies

## Install

```sh
agentstack add skill-lujiafa-houtu-project-skills-houtu-dependencies
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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):**
  ```xml
  
  
      io.github.lujiafa
      houtu-dependencies
      ${version}
      pom
      import
  
  ```
  **Gradle (build.gradle / build.gradle.kts):**
  ```kotlin
  // 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:
  ```xml
  
  
      io.github.lujiafa
      spring-cloud-houtu
      ${version}
      pom
      import
  
  ```
  ```kotlin
  // 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 `` 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 ``
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 :`:

```bash
git show :
# 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` + `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` | 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` 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        (interface: getCode(), getMessage(), getData())
├── ResponseData        (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       (pagination data DTO, contains records/totalRecords/totalPages)

BaseVO                     (view object base class, implements Serializable)

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

**PageDataVO static factory methods:**
- `PageDataVO.build(PageDataDTO dto, Class clazz)` — Convert from DTO
- `PageDataVO.build(currentPage, pageSize, totalRecords, List 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,

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lujiafa](https://github.com/lujiafa)
- **Source:** [lujiafa/houtu-project-skills](https://github.com/lujiafa/houtu-project-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lujiafa-houtu-project-skills-houtu-dependencies
- Seller: https://agentstack.voostack.com/s/lujiafa
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.