Java / Spring Boot server example

This is a back-end-only Spring Boot example with sample code, configuration and an HTTP request sequence, with no web page and no front-end dependencies. It shows how your business back end integrates with IM; try client-side chat alongside the existing H5 demo.

Build and start

You need JDK 17 or later and Maven 3.9 or later. Run mvn clean package in sdk/server/java, then set the environment variables IM_BASE_URL, IM_ORG_NAME, IM_APP_NAME, IM_CLIENT_ID and IM_CLIENT_SECRET, plus an example access token IM_DEMO_ACCESS_TOKEN of at least 16 characters.

java -jar demo/target/im-java-demo-1.0.0-alpha.3.jar
curl -fsS http://127.0.0.1:18930/demo/api/status \
  -H "X-Demo-Token: $IM_DEMO_ACCESS_TOKEN"

The example listens only on the local address by default, and IM_JAVA_DEMO_PORT changes the port; the root path returns 404. Credentials stay on the back end, and the example's access token is only for local debugging. Real services must use their own authentication and authorization, and never let anyone issue sign-in tickets for arbitrary users or call app-level management operations.

Structure and flow

Example	Use
AccountController	Create, query, update and delete accounts, and issue sign-in tickets for business users
MessageController	Send business notifications, query the admin view of history, recall messages
GroupController	Create and update groups, add members, dissolve groups
ServiceExamples / OperationsController	Friends and blocklists, push, presence, lists of moderation items, calls and channels, chat room announcements, uploading and downloading files from Java
CallbackReceiver	Verifying signatures over the raw request body, handling events asynchronously, allowing or rejecting in sync callbacks
ApiErrors / DemoSecurity	Error code mapping, and access protection for the example's endpoints

A suggested order: create two test users, issue sign-in tickets and have a client sign in with them; then send one-to-one and group messages, query history and recall a message. Duplicate usernames, invalid parameters and a nonexistent recipient trigger real failures, and sending again with the same client_msg_id shows de-duplication.

The full request sequence is in sdk/server/java/demo/requests.http in the repository. File upload and download are only shown as calls from Java business components; there's no HTTP endpoint that reads arbitrary local files. For other operations, call the 15 services of DRClient directly; the example doesn't add a management route for each of the 198 APIs.

Callbacks

In the console, add an /im/callback address the IM service can reach, set IM_CALLBACK_ENDPOINT_ID and IM_CALLBACK_SECRET, and verify the address after starting the example. Request GET /demo/api/callbacks with the example's access token to see the latest 100 events kept in memory. Real services should persist events idempotently, and implement a shared CallbackStore for several instances.

The message.before_send sync callback example rejects messages whose body contains [禁止发送]; it only affects real sending once that sync callback is turned on in the console. The automated tests tell real asynchronous events apart from signed requests they build themselves. In containers, the callback address must be a host address the IM service can reach; the example doesn't work around production network restrictions.

Tests and reports

Run make sdk-server-java-test from the repository root for the unit tests and contract tests of the 198 APIs. If the repository's test service (sdk/conformance/harness) is already running locally, you can also run the repository's integration test script: it builds the latest Jar, verifies business integration, failure cases and callbacks against the real service, and cleans up the resources and processes it created.

The tests need no browser and take no screenshots; the test report is generated from structured results and JUnit XML. Passing every API contract test doesn't mean all 198 APIs were verified in real business use; the report states what was actually covered and what wasn't.