# NewLife.WeChat NewLife.WeChat 是一个基于 NewLife.Core 和 XCode 的微信开发工具类库，提供微信公众号、小程序等功能的集成支持。 ## 功能特性 - ✅ 基于 NewLife.Core 核心库，提供强大的基础功能 - ✅ 使用 XCode 实体模型管理配置，支持多种数据库 - ✅ 支持多应用配置管理（公众号、小程序、APP） - ✅ AccessToken 自动管理和缓存（提前5分钟过期） - ✅ 用户信息获取（OpenId、UnionId） - ✅ UnionId 跨应用关联查询 - ✅ 模板消息发送（公众号模板消息、小程序订阅消息） - ✅ 批量消息发送支持 - 🔄 更多微信 API 支持（开发中） ## 核心功能 ### 1. AccessToken 管理 - 自动缓存，减少 API 调用 - 提前5分钟过期，避免临界问题 - 并发安全，防止重复请求 - 支持强制刷新 ### 2. 用户信息获取 - 网页授权获取用户信息 - 自动解析 OpenId 和 UnionId - 存储到数据库，便于管理 ### 3. UnionId 关联查询 - 通过 UnionId 实现跨应用用户识别 - 支持公众号、小程序、APP 用户关联 - 适用于跨应用消息推送、数据同步等场景 ### 4. 模板消息发送 - 支持公众号模板消息 - 支持小程序订阅消息 - 支持批量发送 - 自动获取 AccessToken - 完整的错误处理和重试机制 ## 快速开始 ### 安装 ```bash dotnet add package NewLife.WeChat ``` ### 配置数据库连接 在配置文件（如 `appsettings.json`）中配置数据库连接： ```json { "ConnectionStrings": { "WeChat": "Data Source=Data/WeChat.db" } } ``` ### 初始化配置 ```csharp using NewLife.WeChat.Entities; // 创建公众号配置 var config = new 微信配置 { AppName = "我的公众号", AppId = "wx1234567890", AppSecret = "your_app_secret", AppCategory = 1, // 1=公众号 IsEnabled = true }; config.Insert(); ``` ### 使用示例 ```csharp using NewLife.WeChat.Services; var service = new WeChatService(); // 1. 获取 AccessToken var token = await service.GetAccessTokenAsync("wx1234567890"); // 2. 获取用户信息 var userInfo = await service.GetUserInfoByCodeAsync("wx1234567890", code); // 3. 跨应用查询 var miniOpenId = service.GetOpenIdByUnionId(userInfo.UnionId, "wx_mini_123456"); // 4. 发送模板消息 var data = new { first = new { value = "您的订单已完成" }, keyword1 = new { value = "202401010001" }, keyword2 = new { value = "￥99.00" }, remark = new { value = "感谢支持！" } }; await service.SendTemplateMessageAsync( "wx1234567890", userInfo.OpenId, "template_order_success", data, "https://example.com/order/202401010001" ); ``` ## 文档 - [快速开始指南](/NewLife/NewLife.WeChat/Blob/master/docs/QuickStart.md) - 详细的使用教程 - [架构设计文档](/NewLife/NewLife.WeChat/Blob/master/docs/Architecture.md) - 系统架构和设计说明 - [核心功能实现](/NewLife/NewLife.WeChat/Blob/master/docs/CoreFunctions.md) - 核心功能实现细节 ## API 列表 ### WeChatService 核心服务 | 方法 | 说明 | |------|------| | `GetAccessTokenAsync` | 获取访问令牌（自动缓存） | | `RefreshAccessTokenAsync` | 刷新访问令牌 | | `GetUserInfoByCodeAsync` | 通过授权码获取用户信息 | | `GetUserDetailAsync` | 获取用户详细信息 | | `GetOpenIdByUnionId` | 根据 UnionId 查询指定应用的 OpenId | | `GetAllOpenIdsByUnionId` | 获取 UnionId 关联的所有 OpenId | | `SendTemplateMessageAsync` | 发送公众号模板消息 | | `SendSubscribeMessageAsync` | 发送小程序订阅消息 | | `SendBatchTemplateMessagesAsync` | 批量发送模板消息 | ### 实体类 | 实体 | 说明 | |------|------| | `微信配置` | 微信应用配置表 | | `微信用户` | 微信用户表（OpenId、UnionId） | | `微信模板消息配置` | 模板消息配置表 | ## 技术栈 - .NET 10.0 - NewLife.Core - 核心基础库 - XCode - 数据访问层框架 ## 开发计划 ### ✅ 已完成 - [x] 项目架构设计 - [x] 实体模型实现（微信配置、微信用户、模板消息配置） - [x] AccessToken 管理（获取、缓存、刷新） - [x] 用户信息获取（OpenId、UnionId） - [x] UnionId 跨应用关联查询 - [x] 模板消息发送（公众号、小程序） - [x] 批量消息发送 ### 🔄 进行中 - [ ] 消息管理（接收、回复） - [ ] 菜单管理 - [ ] 素材管理 ### 📋 计划中 - [ ] 支付功能 - [ ] 客服消息 - [ ] 小程序码生成 - [ ] 企业微信支持 - [ ] 发送记录和统计 ## 贡献 欢迎提交 Issue 和 Pull Request！ ## 许可证 MIT License --- **维护者**: NewLife 开发团队 **主页**: https://git.newlifex.com/NewLife/NewLife.WeChat remark = new { value = "感谢支持！" } }; await service.SendTemplateMessageAsync( "wx1234567890", userInfo.OpenId, "template_order_success", data, "https://example.com/order/202401010001" ); ``` } } ``` ### 创建微信配置 ```csharp using NewLife.WeChat.Entities; using NewLife.WeChat.Models; // 创建公众号配置 var config = new 微信配置 { AppName = "我的公众号", AppId = "wx1234567890abcdef", AppSecret = "your_app_secret_here", AppCategory = WeChatAppCategory.公众号, TenantId = 1, IsEnabled = true, Token = "your_token", Remark = "测试公众号" }; config.Insert(); // 创建小程序配置 var miniConfig = new 微信配置 { AppName = "我的小程序", AppId = "wx9876543210fedcba", AppSecret = "your_mini_app_secret", AppCategory = WeChatAppCategory.MiniProgram, TenantId = 1, IsEnabled = true, Remark = "测试小程序" }; miniConfig.Insert(); // 创建APP配置 var appConfig = new 微信配置 { AppName = "我的移动应用", AppId = "wxapp123456789", AppSecret = "your_app_secret", AppCategory = WeChatAppCategory.APP, TenantId = 1, IsEnabled = true, Remark = "移动APP应用" }; appConfig.Insert(); ``` ### 查询配置 ```csharp // 根据 AppId 查询 var config = 微信配置.FindByAppId("wx1234567890abcdef"); // 查询所有启用的配置 var configs = 微信配置.FindAllEnabled(); // 根据应用分类查询 var officialAccounts = 微信配置.FindAllByCategory(WeChatAppCategory.公众号); var miniPrograms = 微信配置.FindAllByCategory(WeChatAppCategory.MiniProgram); var apps = 微信配置.FindAllByCategory(WeChatAppCategory.APP); // 根据租户查询 var tenantConfigs = 微信配置.FindAllByTenant(1); // 高级查询 var list = 微信配置.Search( appname: null, appid: null, apptype: null, category: WeChatAppCategory.公众号, tenantId: 1, enabled: true, start: DateTime.MinValue, end: DateTime.MaxValue, key: "测试", page: new PageParameter { PageIndex = 1, PageSize = 20 } ); ``` ### AccessToken 管理 ```csharp var config = 微信配置.FindByAppId("wx1234567890abcdef"); // 设置 AccessToken config.SetAccessToken("access_token_value", 7200); // 获取 AccessToken var token = config.GetAccessToken(); ``` ### 微信用户管理 ```csharp using NewLife.WeChat.Entities; // 根据 AppId 和 OpenId 查找用户 var user = 微信用户.FindByOpenId("wx1234567890abcdef", "openid123"); // 查找同一 UnionId 的所有用户（跨应用） var users = 微信用户.FindAllByUnionId("unionid123"); // 同步用户信息（从微信API获取后更新） var userInfo = new Dictionary<String, Object> { ["unionid"] = "unionid123", ["nickname"] = "张三", ["headimgurl"] = "http://...", ["sex"] = 1, ["country"] = "中国", ["province"] = "广东", ["city"] = "深圳", ["subscribe"] = 1, ["subscribe_time"] = 1234567890 }; var syncedUser = 微信用户.Sync("wx1234567890abcdef", "openid123", userInfo); // 查询所有已关注用户 var subscribedUsers = 微信用户.FindAllSubscribed(); // 高级查询 var list = 微信用户.Search( appid: "wx1234567890abcdef", openid: null, unionid: null, nickname: "张", isSubscribe: true, start: DateTime.MinValue, end: DateTime.MaxValue, key: "深圳", page: new PageParameter { PageIndex = 1, PageSize = 20 } ); ``` ## 项目结构 ``` NewLife.WeChat/ ├── Entities/ # XCode 实体模型 │ ├── 微信配置.cs # 配置实体定义 │ ├── 微信配置.Biz.cs # 配置业务逻辑 │ ├── 微信用户.cs # 用户实体定义 │ └── 微信用户.Biz.cs # 用户业务逻辑 ├── docs/ # 文档 │ └── Architecture.md # 架构设计文档 └── README.md # 项目说明 ``` ## 数据库支持 得益于 XCode 的支持，本项目支持以下数据库： - SQLite（默认） - MySQL - SQL Server - PostgreSQL - Oracle - 等等... ## 架构设计 详细的架构设计请参考 [架构文档](/NewLife/NewLife.WeChat/Blob/master/docs/Architecture.md)。 ## 依赖项 - [NewLife.Core](https://github.com/NewLifeX/X) - 核心基础库 - [NewLife.XCode](https://github.com/NewLifeX/X) - 数据访问层框架 ## 开发计划 - [x] 基础架构搭建 - [x] 微信配置实体模型 - [ ] AccessToken 自动刷新服务 - [ ] 微信公众号 API 封装 - [ ] 微信小程序 API 封装 - [ ] 微信支付支持 - [ ] 企业微信支持 ## 贡献 欢迎提交 Issue 和 Pull Request！ ## 许可证 MIT License ## 联系方式 - 官网：https://newlifex.com - QQ群：1600800 - 源码：https://git.newlifex.com/NewLife/NewLife.WeChat