Java / Spring Boot 服务端示例

这是一个只有后端的 Spring Boot 示例，包括示例代码、配置和 HTTP 请求序列，没有网页，也不依赖前端。它演示你的业务后端怎样接入 IM；客户端的聊天可以配合已有的 H5 Demo 一起试。

构建与启动

需要 JDK 17 以上和 Maven 3.9 以上。在 sdk/server/java 中执行 mvn clean package，再配置环境变量 IM_BASE_URL、IM_ORG_NAME、IM_APP_NAME、IM_CLIENT_ID、IM_CLIENT_SECRET，以及至少 16 位的示例访问口令 IM_DEMO_ACCESS_TOKEN。

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"

示例默认只监听本机地址，端口可以用 IM_JAVA_DEMO_PORT 修改；访问根路径返回 404。凭据只保存在后端，示例的访问口令只用于本机调试。正式的业务要接入自己的身份认证和授权，不能让任何人随意为任意用户签发登录凭证，或调用应用级的管理操作。

示例结构与流程

示例	用途
AccountController	创建、查询、修改、删除账号，为业务用户签发登录凭证
MessageController	发送业务通知、查询管理视角的历史、撤回消息
GroupController	建群、修改群、添加成员和解散群
ServiceExamples / OperationsController	好友和黑名单、推送、在线状态，审核、通话和频道的列表，聊天室公告，在 Java 中上传和下载文件
CallbackReceiver	用原始请求体校验签名，异步处理事件，同步回调中允许或拒绝
ApiErrors / DemoSecurity	错误码映射，以及示例接口的访问保护

建议的顺序：先创建两个测试用户，签发登录凭证，由客户端用它登录；再发送单聊和群聊消息、查询历史、撤回消息。用重复的用户名、非法的参数、不存在的接收方可以触发真实的失败；用相同的 client_msg_id 重复发送可以验证去重。

完整的请求序列见仓库中的 sdk/server/java/demo/requests.http。文件的上传和下载只给出在 Java 业务组件中调用的示例，不提供读取本机任意文件的 HTTP 接口。其他操作直接调用 DRClient 的 15 个服务，示例没有为 198 个接口逐一做管理路由。

回调

在控制台中添加一个 IM 服务能访问到的 /im/callback 地址，设置 IM_CALLBACK_ENDPOINT_ID 和 IM_CALLBACK_SECRET，启动示例后完成地址验证。用示例的访问口令请求 GET /demo/api/callbacks，可以查看保存在内存中的最近 100 条事件。正式的业务要把事件幂等地持久保存；多个实例时要实现共享的 CallbackStore。

同步回调 message.before_send 的示例会拒绝正文包含 [禁止发送] 的消息；需要在控制台中开启对应的同步回调，才会影响真实的发送。自动测试会区分真实的异步事件和自己构造的带签名请求。在容器中运行时，回调地址要用 IM 服务能访问到的宿主机地址；示例不会绕过生产环境的网络限制。

测试与报告

在仓库根目录运行 make sdk-server-java-test，执行单元测试和 198 个接口的契约测试。如果本机已经启动了仓库中的测试服务（sdk/conformance/harness），还可以运行仓库中的集成测试脚本：它构建最新的 Jar，连真实服务验证业务接入、失败场景和回调，结束后清理自己创建的资源和进程。

测试不需要浏览器，也不截图；测试报告由结构化的结果和 JUnit XML 自动生成。接口的契约测试全部通过，不代表 198 个接口都在真实业务中验证过；实际覆盖的范围和没有覆盖的部分，以测试报告为准。