# isteinsgate/wechatpay-java architecture

> Architecture diagram of the GitHub repository isteinsgate/wechatpay-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/isteinsgate/wechatpay-java
- Repository: https://github.com/isteinsgate/wechatpay-java

## Overview

##### Project Type and Purpose
- This is an **open-source Java SDK** (client library) for calling WeChat Pay APIv3.
- It is **not** a deployable service or microservice but a **layered library** offering:
- A **core** module for HTTP transport, signing, encryption, and notification handling.
- A **service** module that implements each business API (payments, refunds, profit-sharing, etc.) and provides example code.
- Optional **shangmi** (国密) extension and test harness modules.

A. Client Application (your code that calls the SDK)
B. Service Module
- Sub-components: `payments`, `refund`, `certificate`, `billdownload`, etc.
C. Core Module
- HTTP Client Layer (`AbstractHttpClient`, `OkHttpClientAdapter`, `DefaultHttpClientBuilder`)
- Crypto Layer (`Signer`/`Verifier`, `PrivacyEncryptor`/`PrivacyDecryptor`, `AeadAesCipher`)
- Certificate Management (`AutoCertificateService`, `CertificateDownloader`, in-memory providers)
- Notification Handling (`NotificationParser`, `NotificationConfig` variants)
- Utilities (JSON, I/O, nonces, PEM handling)
D. External Systems
- WeChat Pay API Endpoints (`api.mch.weixin.qq.com` & fallback `api2.wechatpay.cn`)
- WeChat Pay Platform Certificates
- Merchant Resources (merchant private key, APIv3 key)

1. **Initialization**
- Client → Core.Config (e.g. `RSAAutoCertificateConfig.Builder`)
- Core.Config → AutoCertificateService (downloads platform certs)
2. **Business Request**
- Client → Service.<X>Service → Core.HttpClient
- HttpClient → Crypto.Signer (sign request)
- HttpClient → HTTP → WeChat Pay Server
- Response → HttpClient → Crypto.Verifier (verify resp. signature) → Decrypt (if needed) → Service returns domain object to Client
3. **Notification Handling**
- WeChat Pay → HTTP callback endpoint → Client wraps raw body/headers into `RequestParam` → Core.NotificationParser (verifies + decrypts) → Domain event object returned to Client
4. **Manual/Advanced HTTP**
- Client → `OkHttpClientAdapter` (for unsupported APIs) → same sign/verify flows
5. **Bill Download**
- Two-step: Service requests download URL → HttpClient.download() → stream data → Client verifies digest

##### Architectural Patterns & Design Principles
- **Layered Architecture**: Clear separation between Core (infrastructure) and Service (business APIs).
- **Builder Pattern**: All configs and service instantiations use fluent builders.
- **Adapter Pattern**: `OkHttpClientAdapter` implements a generic `HttpClient` API.
- **Strategy Pattern**: Pluggable `NotificationConfig`, `PrivacyEncryptor`, `PrivacyDecryptor`.
- **Facade**: Service classes present a simple API masking core complexity.
- **Background Processing**: `AutoCertificateService` uses a scheduled thread.

##### Major Technologies & Frameworks
- Java 1.8+
- Gradle multi-project build
- OkHttp for HTTP
- SLF4J for logging
- Gson for JSON
- JUnit/TestNG for tests
- Tencent Kona SMSuite (国密) in `shangmi` module

##### Essential Checklist
[ ] Core and Service modules clearly separated
[ ] Crypto and HTTP sub-components inside Core labeled
[ ] Notification handling path included
[ ] Dual-domain retry strategy noted on HTTP client
[ ] Extension module `shangmi` shown as optional plugin
[ ] Config builders and background cert-refresh thread called out

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    subgraph "Client Application"
        Client["Client Application"]:::client
        example["QuickStart Example"]:::example
    end

    %% Service Module
    subgraph "Service Module" 
        payments["Payments Service"]:::service
        refund["Refund Service"]:::service
        certificateSvc["Certificate Service"]:::service
        billdownload["Bill Download Service"]:::service
    end

    %% Core Module
    subgraph "Core Module"
        subgraph "Configuration & Builders"
            config1["RSAAutoCertificateConfig"]:::core
            config2["AbstractRSAConfigBuilder"]:::core
        end
        subgraph "HTTP Client Layer"
            httpAbstract["AbstractHttpClient"]:::core
            httpBuilder["DefaultHttpClientBuilder"]:::core
            okhttpAdapter["OkHttpClientAdapter\nOkHttpMultiDomainInterceptor"]:::core
        end
        subgraph "Crypto Layer"
            signer["Signer"]:::core
            verifier["Verifier"]:::core
            aead["AeadAesCipher"]:::core
            privacy["PrivacyEncryptor\nPrivacyDecryptor"]:::core
        end
        subgraph "Certificate Management"
            autoCert["AutoCertificateService"]:::core
            certDownloader["CertificateDownloader"]:::core
            inMemoryProv["InMemoryCertificateProvider"]:::core
        end
        subgraph "Notification Handling"
            notifier["NotificationParser\nNotificationConfig"]:::core
        end
        subgraph "Utilities"
            util["GsonUtil\nPemUtil"]:::core
        end
    end

    %% Shangmi Extension
    subgraph "Shangmi Extension (国密)"
        rootShangmi["shangmi Package"]:::ext
        sm4["AeadSM4Cipher"]:::ext
        sm2["SM2Signer\nSM2Verifier\nSM2PrivacyEncryptor\nSM2PrivacyDecryptor"]:::ext
        smNotif["SMNotificationConfig"]:::ext
    end

    %% External Systems
    cloud1["WeChat Pay API\n(api.mch.weixin.qq.com & api2.wechatpay.cn)"]:::external
    cloud2["WeChat Pay Platform Certificates"]:::external
    db["Merchant Private Key\nAPIv3 Key"]:::external

    %% Data Flows
    Client --> example
    example -->|"calls"| payments
    example -->|"calls"| refund
    example -->|"calls"| certificateSvc
    example -->|"calls"| billdownload

    payments -->|"sign + send"| httpAbstract
    refund -->|"sign + send"| httpAbstract
    certificateSvc -->|"sign + send"| httpAbstract
    billdownload -->|"download cert"| httpAbstract

    httpAbstract -->|"uses builder"| httpBuilder
    httpAbstract -->|"adapter"| okhttpAdapter
    httpAbstract -->|"sign"| signer
    httpAbstract -->|"verify"| verifier
    httpAbstract -->|"encrypt/decrypt"| privacy
    httpAbstract -->|"HTTP request"| cloud1
    cloud1 -->|"HTTP response"| httpAbstract
    httpAbstract -->|"verify + decrypt"| verifier
    httpAbstract -->|"notify parser"| notifier

    Client -->|"callback request"| notifier

    Client -->|"init Config"| config1
    Client -->|"init Config"| config2
    config1 -->|"downloads certs"| autoCert
    autoCert -->|"uses downloader"| certDownloader
    certDownloader -->|"stores"| inMemoryProv
    autoCert -->|"scheduled refresh"| autoCert

    billdownload -->|"verify digest"| util

    privacy -->|"国密 extension"| sm4
    privacy -->|"国密 extension"| sm2
    notifier -->|"国密 notifier"| smNotif

    %% Click Events
    click example "https://github.com/isteinsgate/wechatpay-java/blob/main/service/src/example/java/com/wechat/pay/java/service/QuickStart.java"
    click payments "https://github.com/isteinsgate/wechatpay-java/tree/main/service/src/main/java/com/wechat/pay/java/service/payments"
    click refund "https://github.com/isteinsgate/wechatpay-java/tree/main/service/src/main/java/com/wechat/pay/java/service/refund"
    click certificateSvc "https://github.com/isteinsgate/wechatpay-java/tree/main/service/src/main/java/com/wechat/pay/java/service/certificate"
    click billdownload "https://github.com/isteinsgate/wechatpay-java/tree/main/service/src/main/java/com/wechat/pay/java/service/billdownload"
    click config1 "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/RSAAutoCertificateConfig.java"
    click config2 "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/AbstractRSAConfigBuilder.java"
    click httpAbstract "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/http/AbstractHttpClient.java"
    click httpBuilder "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/http/DefaultHttpClientBuilder.java"
    click okhttpAdapter "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/http/okhttp/OkHttpClientAdapter.java"
    click signer "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/cipher/Signer.java"
    click verifier "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/cipher/Verifier.java"
    click aead "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/cipher/AeadAesCipher.java"
    click privacy "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/cipher/PrivacyEncryptor.java"
    click certDownloader "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/certificate/CertificateDownloader.java"
    click autoCert "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/certificate/AutoCertificateService.java"
    click inMemoryProv "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/certificate/InMemoryCertificateProvider.java"
    click notifier "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/notification/NotificationParser.java"
    click util "https://github.com/isteinsgate/wechatpay-java/blob/main/core/src/main/java/com/wechat/pay/java/core/util/GsonUtil.java"
    click rootShangmi "https://github.com/isteinsgate/wechatpay-java/tree/main/shangmi/src/main/java/com/wechat/pay/java/shangmi"
    click sm4 "https://github.com/isteinsgate/wechatpay-java/blob/main/shangmi/src/main/java/com/wechat/pay/java/shangmi/AeadSM4Cipher.java"
    click sm2 "https://github.com/isteinsgate/wechatpay-java/blob/main/shangmi/src/main/java/com/wechat/pay/java/shangmi/SM2Signer.java"
    click smNotif "https://github.com/isteinsgate/wechatpay-java/blob/main/shangmi/src/main/java/com/wechat/pay/java/shangmi/SMNotificationConfig.java"

    %% Styles
    classDef client fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef example fill:#e7f3fe,stroke:#1f77b4,stroke-width:1px
    classDef service fill:#e6f4ea,stroke:#2ca02c,stroke-width:1px
    classDef core fill:#d0e3f0,stroke:#1f77b4,stroke-width:1px
    classDef ext fill:#f9e2d2,stroke:#d62728,stroke-width:1px
    classDef external fill:#ececec,stroke:#999,stroke-dasharray: 5 5,stroke-width:1px
```
