# houtu-dependencies

Adopt this skill: https://proskills.md/skills/other/lujiafa-houtu-project-skills-skills-houtu-dependencies

Page: https://proskills.md/skills/other/lujiafa-houtu-project-skills-skills-houtu-dependencies
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/houtu-dependencies/SKILL.md
size: 8054
upstream: https://github.com/lujiafa/houtu-project-skills/blob/main/skills/houtu-dependencies/SKILL.md

````text
---
name: houtu-dependencies
description: >
  houtu-dependencies enterprise-grade Spring Cloud microservice foundational framework complete usage guide.
  GroupId is io.github.lujiafa, covering unified response, exception handling, parameter parsing,
  session authentication, permission control, signature verification, anti-replay, distributed lock, rate limiting, database field encryption, config decryption,
  access logging, canary routing, weighted load balancing, Feign enhancement, Sentinel circuit breaking, service discovery,
  Swagger documentation, crypto utilities, HTTP client, monitoring metrics, and other enterprise-grade capabilities.
  When the project build file (pom.xml or build.gradle/build.gradle.kts) contains io.github.lujiafa or houtu-related dependencies,
  or when the user mentions houtu or houtu-dependencies,
  this Skill must be read and code must be generated strictly following framework conventions.
  Even if the user is simply doing regular Spring Boot development (e.g., writing Controller, Service, Feign),
  as long as the project includes houtu, the houtu approach must be used instead of native Spring.
  When the user explicitly wants to use the houtu framework and the project has not yet included it, proactively add the BOM and required Starters;
  when the project already includes it, proactively identify and import required module dependencies based on business scenarios during coding,
  naturally integrating framework capabilities to enhance business services based on business semantics, rather than waiting for the user to specify each one.
metadata:
  author: jonlu
  version: "1.1"
---

# 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
  <!-- 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):**
  ```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
  <!-- 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>
  ```
  ```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** —
````

## File: README.md
upstream: https://github.com/lujiafa/houtu-project-skills/blob/main/README.md

````text
# houtu-dependencies

[中文](README-CN.md) | English

> AI Agent autonomous coding guide for the [Houtu](https://github.com/lujiafa/houtu-dependencies) enterprise Java framework.

## Design for AgentCoding

Humans don't participate in writing code. The AI agent loads this skill and produces production-ready code that correctly uses the Houtu framework.

**Three layers of accuracy guarantee:**
1. **Anti-pattern table** — prevents agent from using raw Spring when Houtu provides the capability
2. **Module recipe files** — complete step-by-step: Maven → config → import → code → default-avoid guidelines
3. **Source code verification** — `git show` fallback when API uncertain

## Structure

```
houtu-dependencies/
├── SKILL.md                             # Entry: principles + anti-patterns + version detect + module select
├── references/
│   ├── quick-start.md                   # New project scaffolding recipe
│   ├── module-web.md                    # ResponseData, exception, param binding
│   ├── module-security.md               # Session, auth, RBAC, signing, anti-replay
│   ├── module-cache-lock.md             # @Lock, LockSupport, RateLimiter
│   ├── module-data-security.md          # @SecurityWatch, @SecurityParam
│   ├── module-access-log.md             # @AccessLog, LogFilterHandler
│   ├── module-cloud.md                  # Loadbalancer, Feign, Discovery, Sentinel
│   ├── module-config-decrypt.md         # Configuration value decryption
│   ├── module-swagger.md                # Swagger/OpenAPI auto-config
│   ├── module-utils.md                  # JsonUtils, HttpClients, crypto, BeanUtils
│   ├── module-actuator.md               # Prometheus metrics auto-config
│   ├── module-concurrent.md            # Cross-thread context propagation
│   ├── v3.5.2.md / v3.5.1.md / v3.5.0.md  # Version-specific diffs
│   └── v2.7.3.md / v2.7.2.md / v2.7.1.md  # Version-specific diffs
└── evals/
    └── evals.json                       # 27 test scenarios for validation
```
````
