# finch

**Repository Path**: opensource4clive/finch

## Basic Information

- **Project Name**: finch
- **Description**: 这是一款自研极简轻量级声明式远程调用框架，对标 SpringCloud OpenFeign 核心能力，剔除原生框架冗余依赖、繁杂组件与多余内置功能，主打轻量无侵入、上手简单、性能高效，专为中小型项目、内部微服务简易跨服务调用、非 SpringCloud 生态项目远程接口调用场景设计。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# finch

轻量级声明式 HTTP 远程调用框架，对标 OpenFeign 核心能力。

框架代码位于 **[finch/](finch/)** 子目录（Maven 单模块项目）。

## 技术栈

- JDK 11
- Spring Boot 2.3.4.RELEASE
- JDK 动态代理 + Java 11 `HttpClient` + Fastjson2

## 快速使用

### 1. 定义 API 契约（Spring Web 风格）

```java
@RequestMapping("/api/store")
public interface StoreApi {
    @GetMapping("/{id}")
    Store getById(@PathVariable("id") Long id);
}
```

### 2. 声明 Finch 客户端

```java
@FinchClient(url = "${finch.url.user}")
public interface StoreFeignClient extends StoreApi {
}
```

### 3. 启用扫描

```java
@SpringBootApplication
@EnableFinchClients
public class ConsumerApplication {
}
```

### 4. 注入调用

```java
@RestController
@RequestMapping("/consumer/store")
public class ConsumerController {
    @Resource
    private StoreFeignClient storeFeignClient;

    @GetMapping("/{id}")
    public Store getById(@PathVariable Long id) {
        return storeFeignClient.getById(id);
    }
}
```

## 通信加密（RSA + AES）

开启后，Finch 调用的请求/响应 body 自动加解密，业务代码无感知。

- **Consumer**：仅需 `enabled: true`，所有 `@FinchClient` 出站调用均加解密，**不要**配置 `include-paths`
- **Provider**：`enabled: true` 且配置 `include-paths` 后，仅匹配路径走服务端加解密（保护全部路径可配 `/**`）

| Header | 说明 |
|--------|------|
| `X-Finch-Encrypted-Key` | RSA 加密后的 AES nonce（Base64） |
| `X-Finch-Timestamp` | 请求时间戳（毫秒），防重放 |
| `X-Finch-Trace-Id` | 链路 ID，日志排查 |
| `X-Finch-Original-Content-Type` | 加密前的 Content-Type（json、form 等） |

- **AES**：`AES/GCM`，密钥由 `SHA-256(nonce + timestamp)` 派生，防止单独篡改时间戳
- **RSA**：`RSA/ECB/PKCS1Padding`，加密 16 字节随机 nonce
- **Query 参数**不加密；**body**（含 form）加密
- 同一次请求使用同一 AES 会话密钥加密响应

```yaml
finch:
  security:
    enabled: true
    public-key: <Base64 X.509>
    private-key: <Base64 PKCS#8>
    timestamp-tolerance-ms: 300000
    include-paths:
      - /api/users/**
```

`include-paths` 仅 Provider 配置；未配置时 Consumer 不会注册服务端 Filter。仅 `enabled: true` 时客户端加解密生效。

## 构建

```bash
cd finch && mvn compile
```

## 作者

Clive Yuan