weixin4j: a Java SDK split across WeChat's different platforms

One SDK for several unrelated WeChat APIs

WeChat exposes several distinct product surfaces to developers, each with its own API, its own authentication scheme and its own set of endpoints. Weixin4j exists to wrap those surfaces in Java rather than leaving every team to build the HTTP layer, the token handling and the message formats for itself.

The repository describes itself as a Java toolkit for WeChat development and splits that work into separate projects, or modules, in the Maven sense. The base module carries the HTTP client implementation and the token implementation, which is the part everything else depends on. On top of that sit wrappers for the public platform API, for the enterprise account API, for the mini program API, and a server module for receiving messages.

That module split is the practical shape of the library. You take only what you use, and the README makes one recommendation explicit: if your project only needs the WeChat Pay functionality, you can depend on the base module alone. For most integrations that touch payments and nothing else, that is the whole decision, and it keeps the dependency footprint to one artefact.

The audience is Java developers building WeChat-facing services, which in practice means public accounts, enterprise accounts and mini programs, usually as part of a Chinese market product.

The modules and their versions

The README lists each module with its version, and the versions tell their own story about how the library has grown. The base, public platform and enterprise account modules are all at 1.7.8, the mini program module is at 1.8.0, and the server module is at 1.1.8.

The directory listing in the repository root shows the wider picture:

weixin4j-base
weixin4j-coverage
weixin4j-example
weixin4j-mp
weixin4j-pay
weixin4j-qy
weixin4j-server
weixin4j-serverX
weixin4j-wxa

A weixin4j-pay directory sits alongside the others even though payments are described as part of the base module, and weixin4j-serverX appears as a second server-related module. weixin4j-coverage is clearly the test coverage module, and weixin4j-example is the sample project.

The divergence in version numbers between the mini program module and the rest is worth noticing. It means the modules are released and evolved independently rather than as one synchronised set, which is convenient when you only use part of the library and awkward when you use several parts and want a single upgrade story. The top level also holds assembly.xml and maven-version-rules.xml, the Maven configuration files for assembly and version handling, plus a script directory and a src directory that are not described in the README.

weixin4j-server and the callback side

WeChat platforms push events and messages to a server you expose rather than letting your application poll for them. The weixin4j-server module, described as a Netty server with message dispatch, is the piece that receives those callbacks and routes them.

Netty is the transport, which means the module handles the HTTP server side of the callback endpoint, including the request and response format that WeChat expects. The dispatch layer sits on top of that and is the part that matters to an application: it takes an incoming message and routes it to the handler you registered for that message type.

The README points new users at weixin4j-example for this, describing it as a sample project that shows how to build the weixin4j-server server and how to integrate with Spring, and recommending that you look at it. For a Java team already running Spring, the example is the shortest path to a working callback endpoint, and it also shows the deployment shape the server expects, which is a long-running service rather than a library call inside a request handler.

Payments, tokens and the HTTP layer in the base module

The base module is where the shared plumbing lives. The README describes it as the HTTP client implementation, the token implementation and the WeChat Pay implementation, and then lists the payment surfaces it covers: card payments, QR code scanning payments, JS API payments, APP payments, WAP payments, cash red packets and enterprise transfers.

The token implementation is the piece that ties the other modules together. WeChat APIs authenticate with an access token that has to be obtained and refreshed, and the module centralises that rather than each wrapper inventing its own caching policy. The HTTP client implementation does the same for request signing, retry and error handling across every endpoint the SDK wraps.

The payment list is broader than a simple pay-and-notify flow, and each of those flows has its own parameter set and its own callback semantics. A team implementing red packets or enterprise transfers is working with money movement, and the SDK's job is to marshal the requests and hand you the results. Whether that is enough depends on your own requirements around reconciliation and failure handling, which the README does not describe.

What is planned but not implemented

The README has a section labelled next, and it is a list of WeChat products that the project intends to cover: the WeChat hardware platform, the WeChat store, cards and coupons, physical stores, the shake feature, connecting to Wi-Fi and the scan feature.

None of these are described as available in the current modules, and the section is presented as direction rather than as shipped functionality. That is useful information if you are evaluating the library, because the gap between the public platform, enterprise account and mini program wrappers on one side and these newer surfaces on the other tells you where you would be talking to the raw HTTP API yourself.

The other signposts are the change log at CHANGE.md, the usage wiki and the fact that the default branch is develop. The develop branch as the default is a working branch rather than a stable release branch, which tells you that the default state of the repository is where work happens and that published versions come from somewhere else, in this case Maven Central.

Where weixin4j is the wrong choice

The obvious boundary is scope. This is a WeChat toolkit, so it is irrelevant to any other platform, and inside WeChat it covers the developer-facing APIs that existed when the modules were written. If the product surface you need is one of the items in the next list, you are writing the request handling yourself regardless of which module you depend on.

The second boundary is release engineering. The repository publishes no GitHub releases, so there is no tag list, no release notes on the repository page and no changelog attached to a version. Versions exist on Maven Central, and CHANGE.md is the history, but if your policy requires pinning a commit or reading notes attached to a release, you are working around the project's publishing model rather than with it.

The third boundary is the example. Integration with Spring is demonstrated in weixin4j-example rather than documented as a supported framework integration, and the same applies to how the Netty server is meant to be started, stopped and scaled. For an application with its own dependency injection and configuration system, that part of the design is yours to make.

And there is the licence question, which the next section covers, because the repository metadata and the README do not agree about it.

The licence metadata and the README badge disagree

This is worth flagging plainly, because it is the kind of inconsistency that a build pipeline will not catch and a legal review will.

The README carries a licence badge pointing at the Apache License 2.0 text. The repository's own licence metadata, however, records the licence as a custom licence that GitHub cannot classify, and the project is one of the common cases where a LICENSE file exists but its terms do not match a licence GitHub recognises. The root of the repository does contain a LICENSE file, and the README links the badge to the Apache 2.0 text, so the intent looks clear.

Intent and terms are not the same thing, and the safest reading of the situation is that the LICENSE file governs. This is a description of what the repository states and not legal advice. If your organisation depends on a specific licence, read the LICENSE file in the repository rather than trusting either the badge or the metadata, and if the file's text is ambiguous, ask the maintainer.

On maintenance: the repository is not archived, and the last push was on 2026-07-26. The published artifact for most teams is the Maven Central coordinate under the com.foxinmy group, so the version you depend on is a Maven version rather than a Git tag, and that is the number you should pin in your build.

Editorial conclusion

Adopt weixin4j if you are building a Java service that talks to WeChat, since the modules cover the public platform, enterprise accounts, mini programs and the payment flows without requiring you to write the request and token handling yourself. Do not adopt it for the products listed as next on the project roadmap, which include the hardware platform, the store and card features, and treat the payment module as needing your own review of the settlement rules. Verify first that the module versions you depend on match the API generation you are calling, that the LICENSE file matches the Apache 2.0 terms the README badge advertises, and that the callbacks you need are covered by the dispatching in weixin4j-server.

Frequently asked questions

Official sources

1. foxinmy/weixin4j on GitHub
2. Issues
3. README