{"id":26874338,"url":"https://github.com/wayshall/onetwo-wechat","last_synced_at":"2025-05-07T11:41:40.027Z","repository":{"id":47772575,"uuid":"95507804","full_name":"wayshall/onetwo-wechat","owner":"wayshall","description":"a wechat sdk","archived":false,"fork":false,"pushed_at":"2024-09-05T03:03:14.000Z","size":1036,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-09-06T08:42:32.257Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wayshall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-27T02:11:48.000Z","updated_at":"2024-08-14T03:15:36.000Z","dependencies_parsed_at":"2024-09-06T08:41:09.600Z","dependency_job_id":"c1ca61e0-6187-4f0c-ac1f-3a9394d50aaa","html_url":"https://github.com/wayshall/onetwo-wechat","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayshall%2Fonetwo-wechat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayshall%2Fonetwo-wechat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayshall%2Fonetwo-wechat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wayshall%2Fonetwo-wechat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wayshall","download_url":"https://codeload.github.com/wayshall/onetwo-wechat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252873148,"owners_count":21817703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-31T09:36:29.388Z","updated_at":"2025-05-07T11:41:40.004Z","avatar_url":"https://github.com/wayshall.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# onetwo-wechat\n\n一个简单的基于 Spring RestTemplate 封装的微信sdk\n   \n## 示例项目   \n示例项目，基于spring-boot\n[boot-dbm-sample](https://github.com/wayshall/boot-dbm-sample)\n示例项目，基于jfish\n[onetwo-wechat-sample](https://github.com/wayshall/onetwo-wechat-sample)\n\n## 要求\n- JDK 1.8+\n- Spring 4.0+  \n\n\n## maven\n当前snapshot版本：4.7.4-SNAPSHOT\n\n若使用snapshot版本，请添加snapshotRepository仓储：\n```xml\n\u003crepository\u003e\n     \u003cid\u003eoss\u003c/id\u003e\n     \u003curl\u003ehttps://oss.sonatype.org/content/repositories/snapshots/\u003c/url\u003e\n    \u003csnapshots\u003e\n        \u003cenabled\u003etrue\u003c/enabled\u003e\n    \u003c/snapshots\u003e\n\u003c/repository\u003e   \n```\n\n添加依赖：   \n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.onetwo4j\u003c/groupId\u003e\n    \u003cartifactId\u003eonetwo-wechat\u003c/artifactId\u003e\n    \u003cversion\u003e4.7.4-SNAPSHOT\u003c/version\u003e\n\u003c/dependency\u003e\n\n```\nspring的依赖请自行添加。\n\n\n## 配置\n在使用前需要在spring的下上文（properties或yaml文件）配置下面的属性:\n```Yaml   \nwechat: \n    appid: 开发者ID\n    appsecret: 开发者密码\n    token: 令牌\n    encodingAESKey: 消息加解密密钥，如果不配置，请在微信后台配置使用明文的方式\n\n````\n## 注解启用\n如果只需要使用微信的客户端rest接口，只需要在spring配置类（即有@Configuration注解的类）上加上注解@EnableWechatClient 即可。\n```java     \n  \n\t@EnableWechatClient\n\tpublic class SpringContextConfig {\n\t}   \n   \n```\n\n## 自定义微信接口\n因为微信接口众多，目前只实现了少量接口。所以onetwo-wechat提供了一阵自定义实现微信客户端接口的方式。   \n\n未实现的接口可按下面的方式实现：   \n包约定：\n- 根据微信模块建立相应的包，比如要实现菜单的接口，则创建对应的xxx.menu。   \n- 接口放在api子包下，即：xxx.menu.api\n- 请求的vo放在request子包下，即：xxx.menu.request\n- 响应的vo放在response子包下，即：xxx.menu.response\n\n### 创建自定义的微信接口\n\n比如创建菜单接口\n根据微信的创建菜单接口文档，其http请求地址为：\nhttps://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN   \n\n对应接口代码如下：\n```Java\n@WechatApiClient(path=\"/menu\")\npublic interface MenuService {\n\t\n\t@PostMapping(value=\"/create\", consumes=MediaType.APPLICATION_JSON_UTF8_VALUE)\n\t@WechatRequestConfig(accessToken=true)\n\tWechatResponse create(@RequestBody CreateMenuRequest createMenuRequest);\n\n}\n```   \n\n解释：   \n- 所有微信客户端接口必须使用@WechatApiClient注解标注为微信接口\n- @WechatApiClient注解的path指定本接口下的所有方法的请求路径都是“/menu”的子路径\n- @PostMapping是spring mvc的注解，本库利用了一些spring mvc的现成注解，@PostMapping(value=\"/create\")标识这个方法是post请求，并且请求路径是/menu下的/create。因为https://api.weixin.qq.com/cgi-bin 是@EnableWechatClient默认已经设置了的，所以在编写接口的时候，只需要用相关注解设置/menu/create即可。因为微信的创建菜单接口接收的数据类型为json，所以consumes标记本次请求的requestBody会使用application/json的MediaType。\n- @RequestBody 表示createMenuRequest参数将会作为请求的request body\n- @WechatRequestConfig(accessToken=true)注解的意思是自动获取accessToken并附加到请求的url参数。\n- CreateMenuRequest 是一个VO，表示请求内容，按照微信的文档编写即可。\n- WechatResponse 是一个VO，表示响应内容，按照微信的文档编写即可，这里使用了onetwo-wechat自带的基类。\n\n至此，一个微信rest客户端接口就编写完成了。\n\n### 使用接口\n使用的时候，只需要直接把接口用spring的方式直接注入示例即可使用，如：\n```Java\n\npublic class MenuServiceTest {\n\t\n\t@Autowired\n\tMenuService menuService;\n\t\n\t@Test\n\tpublic void testCreateMenu() throws IOException{\n\t\tString classPath = \"menu_create.json\";\n\n\t\tCreateMenuRequest request = ....;\n\t\tWechatResponse res = menuService.create(request);\n\t\tassertThat(res.isSuccess()).isTrue();\n\t}\n\n}\n```\n\n## 消息接收处理\n\n### 启用和配置微信服务器地址\n@EnableWechatClient 注解默认启用消息接收处理，如果不需要消息处理，可配置enableMessageServe属性为false。\n```java     \n  \n\t@EnableWechatClient\n\tpublic class SpringContextConfig {\n\t}   \n   \n```\nonetwo-wechat会自动注册一系列服务，包括一个请求地址为“/serve”的Controller，所以你只需要在微信后台配置如下服务器地址：\nhttp://你的域名/serve\n\n### 注册消息处理器\n\n```Java\n@Component\npublic class MessageHandlerRegister {\n\n\t@Autowired\n\tMessageRouterService messageRouterService;\n\t\n\t@PostConstruct\n\tpublic void init(){\n\t\tthis.messageRouterService.register(MessageType.TEXT, (TextMessage text)-\u003e{\n\t\t\treturn TextReplyMessage.builder()\n\t\t\t\t\t\t\t\t\t.fromUserName(text.getToUserName())\n\t\t\t\t\t\t\t\t\t.toUserName(text.getFromUserName())\n\t\t\t\t\t\t\t\t\t.content(\"我收到你的消息啦~\")\n\t\t\t\t\t\t\t\t\t.build();\n\t\t});\n\t}\n}   \n\n```\n只需要在spring启动的时候，注入onetwo-wechat的MessageRouterService服务，并通过MessageRouterService的api注册相关类型的消息监听即可。\n上面的示例会在收到消息后简单回复一条\"我收到你的消息啦~\"的信息。\n\n## 企业微信api\n4.7.3 版本增加了对企业微信的支持\n\n### 企业微信的配置方式\n因为企业微信需要对多个应用支持，所以在兼容以前微信配置方式的前提下，增加work-wechat前缀配置以支持企业微信的配置，其中每个企业培训app的配置项都和普通配置的配置方式一样，可以参考WechatConfig\n```yaml\nwork-wechat:\n    apps: \n        party: \n            appid: 企业微信cropid\n            appsecret: 应用秘钥\n            agentId: 应用id\n            encodingAESKey: aes加解密秘钥\n            token: 服务器验证token\n            oauth2: \n                errorInBrowser: false\n                redirectUri: oauth2跳转url，比如http://domian/api/uaa/login/oauth2\n                qrConnectRedirectUri: 扫码登录http://domian/api/uaa/login/qrConnect\n```\n\n### 企业微信登陆支持\n内置实现了oauth2和扫码登录支持。\n用户可以参考或者直接继承WorkLoginController实现业务登录流程。\n比如如果是使用[zifish](https://github.com/wayshall/onetwo)框架，并基于jwt的登录，可以如下实现登录controller：\n```Java\n@RestController\n@RequestMapping(\"/uaa/login\")\npublic class LoginBffController extends WorkLoginController\u003cJwtTokenInfo\u003e {\n\n\t@Autowired\n\tprivate LoginService loginService;\n\n\t@Override\n\tprotected JwtTokenInfo loginByWorkWechatUser(WorkUserLoginInfo workUserLoginInfo) {\n\t\treturn this.loginService.loginByWorkWechatUser(workUserLoginInfo);\n\t}\n\t\n}\n```\n\n### 企业微信消息回调\nWorkEventServeController已经封装了对企业微信消息通知的支持，用户引入依赖后，可以编写一个继承WorkEventServeController的controller即可，启动后可以从控制台的spring mvc的mapping信息中看到controller的路径，默认一般为：/workEventServe\n全路径一般为：http://domain.com/workEventServe/{appid}\n其中appid为配置文件里对应的appid\n\n注册回调处理器可以通过 MessageRouterService 服务，比如监听用户创建：\n```Java\nmessageRouterService.register(ContactChangeTypes.CREATE_USER, ContactCreateUserMessage.class, msg -\u003e {\n\t\t\t\t// 处理业务……\n\t\t\t\treturn \"\";\n\t\t\t});\n```\n\n## 微信网页授权拦截\n\n### 基于zifish的项目\n如果是基于[zifish](https://github.com/wayshall/onetwo)的项目，使用了@EnableJFishBootExtension 注解激活扩展，会自动注册拦截器。\n使用的时候，通过@Interceptor注解把扩展拦截器标注在需要拦截的Controller即可：\n```Java\n@RestController\n@Interceptor(WechatOAuth2MvcInterceptor.class)\npublic class TestController extends AbstractBaseController{\n\n\t@Autowired\n\tprivate WechatUserStoreService sessionStoreService;\n\t\n\t@GetMapping(\"/test\")\n\tpublic Object test(HttpServletRequest request){\n\t\tOAuth2UserInfo userInfo = sessionStoreService.getCurrentUser(request).get();\n\t\treturn userInfo;\n\t}\n\n}\n\n```\n\n### 基于普通的spring mvc或boot的项目\n如果是基于普通的spring mvc或boot的项目，则需要激活@EnableWechatClient注解的enableOAuth2Interceptor属性。\n```java     \n  \n\t@EnableWechatClient(enableOAuth2Interceptor=true)\n\tpublic class SpringContextConfig {\n\t}   \n   \n```\n激活此属性后，onetwo-wechat会自动注册拦截器，拦截器url可通过配置文件wechat.oauth2.intercept.urls属性配置，默认为空，即拦截所有请求。\n\n\n## 腾讯云直播支持\n配置wechat.qcloud.live.enabled=true激活腾讯云的直播支持\n```yaml\nwechat: \n    qcloud: \n        live: \n            enabled: true\n            bizId: \n            pushSafeKey: \n            callback: \n\t    \tenabled: true\n                path: # 默认为：callback\n```\n\n### 监听事件消息通知\n使用注解@LiveMessageListener 和@Subscribe 可以监听腾讯云的事件消息通知，详细事件见：\n[https://cloud.tencent.com/document/api/267/5957](https://cloud.tencent.com/document/api/267/5957)\n目前一共有三种消息：\n- PushMessage ：推流 断流\n- RecordingMessage ：新录制文件\n- ScreenShotMessage：新截图文件\n```Java\n@LiveMessageListener\npublic class PushMessageListener {\n\n\t@Subscribe\n\tpublic void onMessage(PushMessage message) {\n\t\tif(message.isPushEvent()){\n\t\t\tSystem.out.println(\"有人来直播了！！！\");\n\t\t}else{\n\t\t\tSystem.out.println(\"有人关闭了直播\");\n\t\t}\n\t}\n\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwayshall%2Fonetwo-wechat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwayshall%2Fonetwo-wechat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwayshall%2Fonetwo-wechat/lists"}