# wechatapi-java

**Repository Path**: iteer/wechatapi-java

## Basic Information

- **Project Name**: wechatapi-java
- **Description**: A Java SDK for the WeChat Official Account and Payment APIs.
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# wechatapi-java

**A lightweight, zero-magic Java SDK for the WeChat Official Account & Payment APIs.**

[![License: Apache 2.0](https://img.shields.io/github/license/javaeer/wechatapi-java?style=flat-square)](LICENSE)
[![Java](https://img.shields.io/badge/Java-8-ED8B00?style=flat-square&logo=openjdk&logoColor=white)](https://www.java.com/)
[![Maven](https://img.shields.io/badge/Maven-3.6%2B-0091EA?style=flat-square)](https://maven.apache.org/)
[![Version](https://img.shields.io/badge/version-1.0.0--alpha-orange?style=flat-square)](https://github.com/javaeer/wechatapi-java/releases)
[![Top Language](https://img.shields.io/github/languages/top/javaeer/wechatapi-java?style=flat-square)](https://github.com/javaeer/wechatapi-java)

</div>

---

## 📖 简介 / Introduction

`wechatapi-java` 是一个**轻量级、零黑魔法的微信 Java SDK**，面向微信小程序 / 公众号的**授权登录、手机号获取、虚拟支付**等场景。

- 🧱 **纯手工封装**：仅依赖 OkHttp + Jackson，无 Spring / 无框架侵入，可嵌入任意 Java 8+ 项目
- 🔌 **可插拔 HTTP**：内置 OkHttp 适配器，并支持多域名拦截；也可传入自定义 `HttpClient`
- 🔐 **数据解密与签名**：提供 AES 数据解密（`WechatDataCryptUtils`）与签名工具（`WechatSignatureUtils`）
- 🏗 **Builder 风格**：配置与服务均以 Builder 构造，链式、可读、易测试
- 📦 **面向发布**：已配置 `source` / `javadoc` / `gpg` 与 Central Publishing 插件，可直接发布到 Maven Central

> 当前版本为 `1.0.0-alpha`，虚拟支付（签名部分）仍在完善中，生产使用前请充分自测。

## 📦 模块概览 / Modules

| 模块 | 说明 | 关键类 |
| --- | --- | --- |
| 授权登录 | `code2Session`、获取 `access_token` / `stable_token` | `WechatAuthService` |
| 手机号 | 获取并解密用户手机号 | `WechatPhoneNumberService` |
| 虚拟支付 | 下单、查单、取消支付、余额、赠送 | `WechatVirtualPayService` |
| 核心 HTTP | 请求/响应模型、OkHttp 适配器、多域名拦截 | `core.http.*` |
| 工具 | JSON、字符串、数据解密、签名 | `utils.*` |
| 异常 | 统一的微信 API 异常体系 | `core.exception.*` |

## 🛠 技术栈 / Tech Stack

| 依赖 | 版本 | 用途 |
| --- | --- | --- |
| Java | 8 | 运行环境 |
| [OkHttp](https://square.github.io/okhttp/) | 4.9.3 | HTTP 客户端 |
| [Jackson](https://github.com/FasterXML/jackson) | 2.11.1 | JSON 序列化 |
| [Lombok](https://projectlombok.org/) | 1.18.12 | 代码简化 |
| [Guava](https://github.com/google/guava) | 32.0.0-jre | 工具集合 |
| commons-lang3 | 3.12.0 | 字符串 / 工具 |
| commons-text | 1.14.0 | 文本处理 |
| SLF4J / Logback | 1.7.30 / 1.2.12 | 日志 |

## 🚀 安装 / Installation

### Maven Central（发布后可用）

```xml
<dependency>
    <groupId>cn.net.yunlou</groupId>
    <artifactId>wechatapi-java</artifactId>
    <version>1.0.0-alpha</version>
</dependency>
```

### 立即可用：JitPack

```xml
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.javaeer</groupId>
    <artifactId>wechatapi-java</artifactId>
    <version>master</version>
</dependency>
```

### Gradle (Kotlin DSL)

```kotlin
dependencies {
    implementation("cn.net.yunlou:wechatapi-java:1.0.0-alpha") // 或 com.github.javaeer:wechatapi-java:master
}
```

## ⚡ 快速开始 / Quick Start

### 1. 构造配置与 HTTP 客户端

```java
import cn.net.yunlou.wechat.api.core.Config;
import cn.net.yunlou.wechat.api.core.DefaultConfig;
import cn.net.yunlou.wechat.api.core.http.DefaultHttpClientBuilder;
import cn.net.yunlou.wechat.api.core.http.HttpClient;

Config config = new DefaultConfig.Builder()
        .appId("你的 AppId")
        .appSecret("你的 AppSecret")
        .build();

HttpClient httpClient = new DefaultHttpClientBuilder()
        .config(config)
        .build();
```

### 2. 授权登录（code2Session / access_token）

```java
import cn.net.yunlou.wechat.api.service.WechatAuthService;
import cn.net.yunlou.wechat.api.core.entity.WechatSession;
import cn.net.yunlou.wechat.api.core.entity.WechatAccessToken;

WechatAuthService authService = new WechatAuthService.Builder()
        .config(config)        // 也可 .httpClient(httpClient).appId(...).appSecret(...)
        .build();

// 小程序登录：用 wx.login 拿到的 code 换取 session
WechatSession session = authService.code2Session("前端传来的 js_code");
// session.getOpenid() / getSessionKey() / getUnionid() ...

// 获取接口调用凭证（普通 / 稳定版）
WechatAccessToken token = authService.getAccessToken();
// 或 authService.getStableAccessToken();
String accessToken = token.getAccessToken();
```

### 3. 获取手机号

```java
import cn.net.yunlou.wechat.api.service.WechatPhoneNumberService;
import cn.net.yunlou.wechat.api.core.entity.WechatUserPhone;

WechatPhoneNumberService phoneService = new WechatPhoneNumberService.Builder()
        .config(config)
        .build();

// code 来自 <button open-type="getPhoneNumber"> 回调
WechatUserPhone phone = phoneService.getWechatUserPhoneNumber(accessToken, "phone_number_code");
// phone.getPhoneNumber() ...
```

### 4. 虚拟支付（进行中）

```java
import cn.net.yunlou.wechat.api.service.WechatVirtualPayService;
import cn.net.yunlou.wechat.api.model.VirtualPayRequest;
import cn.net.yunlou.wechat.api.core.entity.WechatVirtualPay;

WechatVirtualPayService payService = new WechatVirtualPayService.Builder()
        .config(config)
        .build();

VirtualPayRequest request = VirtualPayRequest.builder()
        // .openid(...) .outTradeNo(...) .amount(...) ...
        .build();

WechatVirtualPay order = payService.pay(accessToken, request);
```

> ⚠️ 虚拟支付的签名（`signature` / `paySignature`）当前为占位实现，正式接入前请参考微信官方文档补全 `WechatSignatureUtils` 与 `WechatVirtualPayService` 中的 TODO。

### 5. 异常处理

所有接口调用抛出统一的 `WechatApiException`；更细粒度还有 `HttpException`、`ValidationException`、`DecryptionException`、`MalformedMessageException`、`ServiceException`，便于分层处理：

```java
try {
    WechatSession session = authService.code2Session(code);
} catch (WechatApiException e) {
    // e.getErrcode() / e.getErrmsg()
    log.error("微信接口调用失败：{}", e.getErrmsg());
}
```

## 📁 项目结构 / Project Structure

```text
src/main/java/cn/net/yunlou/wechat/api/
├── core/                 # 配置、实体、HTTP 客户端抽象、异常
│   ├── Config.java           # 配置接口（appId / appSecret）
│   ├── DefaultConfig.java    # 默认配置实现（Builder）
│   ├── entity/               # 响应实体（Session / Token / Phone / VirtualPay ...）
│   ├── exception/            # 异常体系
│   └── http/                 # 请求/响应模型 + OkHttp 适配器
│       └── okhttp/           # OkHttpClientAdapter / 多域名拦截器
├── model/                # 请求 DTO（Auth / PhoneNumber / VirtualPay*）
├── service/              # 业务服务（Auth / PhoneNumber / VirtualPay）
├── utils/                # Json / String / 数据解密 / 签名
└── example/              # 用法示例
```

更详细的设计说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

## 🗺 路线图 / Roadmap

- [x] 授权登录：code2Session / access_token / stable_token
- [x] 手机号获取与解密
- [x] 核心 HTTP 客户端（OkHttp 适配器 + 多域名拦截）
- [~] 虚拟支付：下单 / 查单 / 取消 / 余额 / 赠送（签名待补全）
- [ ] 公众号素材、模板消息、客服消息等更多接口
- [ ] 单元测试覆盖
- [ ] 发布至 Maven Central

## 🤝 贡献 / Contributing

欢迎 Issue、PR 与讨论！提交前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，遵循分支模型与 Conventional Commits。行为准则见 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。

## 🔒 安全 / Security

发现安全漏洞请**不要**公开 Issue，按 [SECURITY.md](SECURITY.md) 私下联系维护者。

## 📄 许可证 / License

基于 [Apache License 2.0](LICENSE) 开源。

## 🙏 致谢 / Acknowledgements

感谢微信开放社区，以及 OkHttp、Jackson 等优秀开源项目。