TJC.Cyclops.Wechat 2026.3.12.2

Cyclops.Wechat

项目概述

Cyclops.Wechat是Cyclops.Framework框架中的微信集成组件，提供与微信平台的全面对接能力，包括微信公众号、微信小程序、企业微信、微信支付和开放平台等服务的统一封装。该组件简化了微信API的调用过程，提供了完整的OAuth认证、消息处理、素材管理、用户管理、模板消息、微信支付等功能，帮助开发者快速构建微信生态应用。

核心功能模块

微信认证

• OAuth2.0授权
• 公众号网页授权
• 小程序授权
• 企业微信授权
• 开放平台授权

消息处理

• 消息接收与解析
• 消息回复与格式化
• 事件推送处理
• 客服消息发送
• 模板消息管理

素材管理

• 临时素材上传下载
• 永久素材管理
• 图文消息编辑
• 视频素材处理
• 素材批量操作

用户管理

• 用户信息获取
• 用户标签管理
• 黑名单管理
• 用户分组
• 用户统计分析

微信支付

• 统一下单API
• 支付回调处理
• 订单查询
• 退款申请
• 企业付款
• 账单下载

小程序

• 小程序码生成
• 订阅消息发送
• 云开发集成
• 数据预拉取
• 内容安全检测

企业微信

• 通讯录管理
• 应用消息推送
• 会话存档
• 审批流程
• 企业支付

技术栈

• .NET 8.0
• ASP.NET Core
• Newtonsoft.Json / System.Text.Json
• Cyclops.Common
• Cyclops.Logging
• Cyclops.Caching
• Cyclops.HttpClient

环境依赖

• .NET 8.0 SDK
• 微信开发者账号（公众号/小程序/开放平台/企业微信）
• 有效的AppID和AppSecret
• 配置的服务器域名和回调地址

安装配置

NuGet安装

Install-Package Cyclops.Wechat

基本配置

在应用程序启动时进行配置：

// 在Program.cs或Startup.cs中
using Cyclops.Wechat;
using Cyclops.Wechat.Configurations;

var builder = WebApplication.CreateBuilder(args);

// 添加Cyclops.Wechat服务
builder.Services.AddCyclopsWechat(options => {
    // 公众号配置
    options.OffiAccount = new OffiAccountOptions {
        AppId = builder.Configuration["Wechat:OffiAccount:AppId"],
        AppSecret = builder.Configuration["Wechat:OffiAccount:AppSecret"],
        Token = builder.Configuration["Wechat:OffiAccount:Token"],
        EncodingAesKey = builder.Configuration["Wechat:OffiAccount:EncodingAesKey"],
        MessageHandlerPath = "/api/wechat/message",
        OAuthRedirectUri = builder.Configuration["Wechat:OffiAccount:OAuthRedirectUri"],
        UseIpProxy = false
    };
    
    // 小程序配置
    options.Miniprogram = new MiniprogramOptions {
        AppId = builder.Configuration["Wechat:Miniprogram:AppId"],
        AppSecret = builder.Configuration["Wechat:Miniprogram:AppSecret"],
        MessageHandlerPath = "/api/wechat/miniprogram/message",
        CloudEnvironmentId = builder.Configuration["Wechat:Miniprogram:CloudEnvironmentId"]
    };
    
    // 微信支付配置
    options.Payment = new PaymentOptions {
        AppId = builder.Configuration["Wechat:Payment:AppId"],
        MchId = builder.Configuration["Wechat:Payment:MchId"],
        Key = builder.Configuration["Wechat:Payment:Key"],
        CertificatePath = builder.Configuration["Wechat:Payment:CertificatePath"],
        CertificatePassword = builder.Configuration["Wechat:Payment:CertificatePassword"],
        NotifyUrl = builder.Configuration["Wechat:Payment:NotifyUrl"],
        ApiV3Key = builder.Configuration["Wechat:Payment:ApiV3Key"],
        EnableSandbox = false
    };
    
    // 企业微信配置
    options.Work = new WorkOptions {
        CorpId = builder.Configuration["Wechat:Work:CorpId"],
        CorpSecret = builder.Configuration["Wechat:Work:CorpSecret"],
        AgentId = int.Parse(builder.Configuration["Wechat:Work:AgentId"]),
        Token = builder.Configuration["Wechat:Work:Token"],
        EncodingAesKey = builder.Configuration["Wechat:Work:EncodingAesKey"]
    };
    
    // 缓存配置
    options.Cache = new CacheOptions {
        AccessTokenCacheKeyPrefix = "wechat:accesstoken:",
        JsApiTicketCacheKeyPrefix = "wechat:jsapi_ticket:",
        CacheExpiration = TimeSpan.FromMinutes(110),
        UseDistributedCache = true
    };
    
    // 日志配置
    options.Log = new LogOptions {
        EnableRequestLog = true,
        EnableResponseLog = false,
        LogLevel = LogLevel.Information
    };
});

var app = builder.Build();

// 配置路由
app.MapControllers();

// 配置微信消息处理中间件
app.UseWechatMessageHandler();

app.Run();

代码示例

微信公众号OAuth认证示例

using Cyclops.Wechat.Services;
using Cyclops.Wechat.Models.OAuth;
using Microsoft.AspNetCore.Mvc;

public class WechatOAuthController : Controller
{
    private readonly IWechatOffiAccountService _wechatService;
    private readonly ILogger<WechatOAuthController> _logger;
    
    public WechatOAuthController(IWechatOffiAccountService wechatService, ILogger<WechatOAuthController> logger)
    {
        _wechatService = wechatService;
        _logger = logger;
    }
    
    /// <summary>
    /// 生成OAuth授权URL
    /// </summary>
    [HttpGet("/oauth/wechat")]
    public IActionResult GetOAuthUrl(string redirectUri = null, string state = null, OAuthScope scope = OAuthScope.Base)
    {
        // 确保重定向URI是完整的
        if (string.IsNullOrEmpty(redirectUri))
        {
            redirectUri = $"{Request.Scheme}://{Request.Host}/oauth/wechat/callback";
        }
        
        // 生成授权URL
        var oauthUrl = _wechatService.GetOAuthUrl(redirectUri, state, scope);
        
        _logger.LogInformation("生成微信OAuth授权URL: {Scope}", scope);
        
        // 重定向到微信授权页面
        return Redirect(oauthUrl);
    }
    
    /// <summary>
    /// OAuth回调处理
    /// </summary>
    [HttpGet("/oauth/wechat/callback")]
    public async Task<IActionResult> OAuthCallback(string code, string state)
    {
        try
        {
            if (string.IsNullOrEmpty(code))
            {
                _logger.LogWarning("微信OAuth回调缺少code参数");
                return BadRequest("授权失败：缺少授权码");
            }
            
            // 获取访问令牌
            var accessTokenResult = await _wechatService.GetOAuthAccessTokenAsync(code);
            
            if (!accessTokenResult.IsSuccess)
            {
                _logger.LogError("获取OAuth访问令牌失败: {Error}", accessTokenResult.ErrorMessage);
                return BadRequest($"授权失败: {accessTokenResult.ErrorMessage}");
            }
            
            // 根据授权范围处理
            if (accessTokenResult.Scope == "snsapi_base")
            {
                // 静默授权，只获取OpenId
                var openId = accessTokenResult.OpenId;
                _logger.LogInformation("微信静默授权成功: {OpenId}", openId);
                
                // 这里可以根据OpenId获取或创建用户
                var userId = await GetOrCreateUserByOpenIdAsync(openId);
                
                // 存储用户会话
                HttpContext.Session.SetString("WechatOpenId", openId);
                HttpContext.Session.SetInt32("UserId", userId);
                
                // 重定向到原始页面或首页
                return Redirect(string.IsNullOrEmpty(state) ? "/" : state);
            }
            else if (accessTokenResult.Scope == "snsapi_userinfo")
            {
                // 获取用户详细信息
                var userInfoResult = await _wechatService.GetOAuthUserInfoAsync(
                    accessTokenResult.AccessToken, 
                    accessTokenResult.OpenId
                );
                
                if (!userInfoResult.IsSuccess)
                {
                    _logger.LogError("获取用户信息失败: {Error}", userInfoResult.ErrorMessage);
                    return BadRequest($"获取用户信息失败: {userInfoResult.ErrorMessage}");
                }
                
                _logger.LogInformation("获取微信用户信息成功: {Nickname}", userInfoResult.Nickname);
                
                // 保存用户信息到数据库
                var userId = await SaveWechatUserInfoAsync(userInfoResult);
                
                // 存储用户会话
                HttpContext.Session.SetString("WechatOpenId", userInfoResult.OpenId);
                HttpContext.Session.SetInt32("UserId", userId);
                
                // 返回用户信息或重定向
                return Redirect(string.IsNullOrEmpty(state) ? "/user/profile" : state);
            }
            
            return BadRequest("未知的授权范围");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "处理微信OAuth回调时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    /// <summary>
    /// 根据OpenId获取或创建用户
    /// </summary>
    private async Task<int> GetOrCreateUserByOpenIdAsync(string openId)
    {
        // 这里应该实现具体的用户查找和创建逻辑
        // 示例中直接返回模拟用户ID
        _logger.LogInformation("根据OpenId获取用户: {OpenId}", openId);
        
        // 实际应用中，应该查询数据库，不存在则创建
        return 1001; // 模拟用户ID
    }
    
    /// <summary>
    /// 保存微信用户信息到数据库
    /// </summary>
    private async Task<int> SaveWechatUserInfoAsync(WechatUserInfo userInfo)
    {
        // 这里应该实现保存用户信息到数据库的逻辑
        _logger.LogInformation("保存微信用户信息: {OpenId}, {Nickname}", 
            userInfo.OpenId, userInfo.Nickname);
        
        // 模拟用户ID
        return 1001;
    }
}

// OAuth配置类扩展
public static class OAuthExtensions
{
    public static void ConfigureWechatOAuth(this IServiceCollection services)
    {
        services.AddAuthentication(options => {
            options.DefaultAuthenticateScheme = "WechatCookie";
            options.DefaultSignInScheme = "WechatCookie";
            options.DefaultChallengeScheme = "Wechat";
        })
        .AddCookie("WechatCookie")
        .AddOAuth("Wechat", options => {
            options.ClientId = Configuration["Wechat:OffiAccount:AppId"];
            options.ClientSecret = Configuration["Wechat:OffiAccount:AppSecret"];
            
            options.CallbackPath = new PathString("/signin-wechat");
            options.AuthorizationEndpoint = "https://open.weixin.qq.com/connect/oauth2/authorize";
            options.TokenEndpoint = "https://api.weixin.qq.com/sns/oauth2/access_token";
            options.UserInformationEndpoint = "https://api.weixin.qq.com/sns/userinfo";
            
            // 自定义参数
            options.Events.OnRedirectToAuthorizationEndpoint = context => {
                var redirectUri = context.RedirectUri;
                // 微信需要特殊处理
                redirectUri = redirectUri.Replace("response_type=code", "response_type=code#wechat_redirect");
                context.Response.Redirect(redirectUri);
                return Task.CompletedTask;
            };
            
            options.ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "openid");
            options.ClaimActions.MapJsonKey(ClaimTypes.Name, "nickname");
            options.ClaimActions.MapJsonKey("headimgurl", "headimgurl");
            
            options.SaveTokens = true;
        });
    }
}

微信消息处理示例

using Cyclops.Wechat.Attributes;
using Cyclops.Wechat.Events;
using Cyclops.Wechat.Models.RequestMessages;
using Cyclops.Wechat.Models.ResponseMessages;
using Cyclops.Wechat.Services;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class WechatMessageController : ControllerBase
{
    private readonly IWechatOffiAccountService _wechatService;
    private readonly ILogger<WechatMessageController> _logger;
    
    public WechatMessageController(IWechatOffiAccountService wechatService, ILogger<WechatMessageController> logger)
    {
        _wechatService = wechatService;
        _logger = logger;
    }
    
    /// <summary>
    /// 微信消息接收验证
    /// </summary>
    [HttpGet("receive")]
    public async Task<IActionResult> Validate([FromQuery] string signature, [FromQuery] string timestamp, [FromQuery] string nonce, [FromQuery] string echostr)
    {
        try
        {
            // 验证签名
            if (_wechatService.CheckSignature(signature, timestamp, nonce))
            {
                _logger.LogInformation("微信消息接收验证成功");
                return Content(echostr);
            }
            else
            {
                _logger.LogWarning("微信消息接收验证失败：签名无效");
                return BadRequest("签名无效");
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "微信消息接收验证过程中发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    /// <summary>
    /// 接收并处理微信消息
    /// </summary>
    [HttpPost("receive")]
    [Consumes("text/xml")]
    public async Task<IActionResult> ReceiveMessage()
    {
        try
        {
            // 读取请求体
            using var reader = new StreamReader(Request.Body);
            var requestXml = await reader.ReadToEndAsync();
            
            _logger.LogInformation("收到微信消息: {Xml}", requestXml);
            
            // 解析消息
            var messageHandler = _wechatService.CreateMessageHandler(requestXml);
            
            // 根据消息类型进行处理
            var responseMessage = await messageHandler.HandleMessageAsync(new MessageHandlerOptions {
                TextMessageHandler = HandleTextMessage,
                ImageMessageHandler = HandleImageMessage,
                VoiceMessageHandler = HandleVoiceMessage,
                VideoMessageHandler = HandleVideoMessage,
                ShortVideoMessageHandler = HandleShortVideoMessage,
                LocationMessageHandler = HandleLocationMessage,
                LinkMessageHandler = HandleLinkMessage,
                EventMessageHandler = HandleEventMessage
            });
            
            // 返回响应消息
            if (responseMessage != null)
            {
                var responseXml = messageHandler.SerializeMessage(responseMessage);
                _logger.LogInformation("返回微信响应消息: {Xml}", responseXml);
                return Content(responseXml, "text/xml");
            }
            
            // 无响应
            return Ok();
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "处理微信消息时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    /// <summary>
    /// 处理文本消息
    /// </summary>
    private async Task<ResponseMessageBase> HandleTextMessage(TextRequestMessage message)
    {
        _logger.LogInformation("收到文本消息: {Content}", message.Content);
        
        // 根据文本内容返回不同的响应
        string responseContent = message.Content switch
        {
            "你好" => "您好！欢迎使用我们的服务。",
            "菜单" => "提供的服务：\n1. 天气查询\n2. 新闻资讯\n3. 客服帮助\n4. 关于我们",
            "天气" => await GetWeatherInfoAsync(),
            "新闻" => await GetNewsSummaryAsync(),
            "客服" => "正在转接人工客服，请稍候...",
            _ => $"收到您的消息：{message.Content}\n回复'菜单'了解更多服务。"
        };
        
        // 返回文本消息
        return new TextResponseMessage(message) {
            Content = responseContent
        };
    }
    
    /// <summary>
    /// 处理图片消息
    /// </summary>
    private async Task<ResponseMessageBase> HandleImageMessage(ImageRequestMessage message)
    {
        _logger.LogInformation("收到图片消息: {MediaId}", message.MediaId);
        
        // 保存图片到临时文件
        var imageUrl = await _wechatService.GetTemporaryMediaUrlAsync(message.MediaId);
        await SaveImageToStorageAsync(imageUrl, message.MediaId);
        
        // 返回图片消息
        return new ImageResponseMessage(message) {
            MediaId = message.MediaId // 可以返回相同或不同的图片
        };
    }
    
    /// <summary>
    /// 处理事件消息
    /// </summary>
    private async Task<ResponseMessageBase> HandleEventMessage(BaseEventMessage message)
    {
        switch (message.EventType)
        {
            case EventType.Subscribe:
                return HandleSubscribeEvent(message as SubscribeEventMessage);
            case EventType.Unsubscribe:
                return HandleUnsubscribeEvent(message as UnsubscribeEventMessage);
            case EventType.Scan:
                return HandleScanEvent(message as ScanEventMessage);
            case EventType.Location:
                return HandleLocationEvent(message as LocationEventMessage);
            case EventType.Click:
                return HandleClickEvent(message as ClickEventMessage);
            case EventType.View:
                return HandleViewEvent(message as ViewEventMessage);
            default:
                _logger.LogWarning("未知的事件类型: {EventType}", message.EventType);
                return null;
        }
    }
    
    /// <summary>
    /// 处理关注事件
    /// </summary>
    private ResponseMessageBase HandleSubscribeEvent(SubscribeEventMessage message)
    {
        _logger.LogInformation("用户关注: {FromUserName}", message.FromUserName);
        
        // 记录关注用户
        Task.Run(() => RecordUserSubscribeAsync(message.FromUserName, message.EventKey));
        
        // 欢迎消息
        string welcomeContent = "欢迎关注我们的公众号！\n\n回复'菜单'了解更多服务。";
        
        // 如果有场景值，个性化欢迎语
        if (!string.IsNullOrEmpty(message.EventKey) && message.EventKey.StartsWith("qrscene_"))
        {
            var sceneId = message.EventKey.Replace("qrscene_", "");
            welcomeContent += $"\n\n您通过场景 {sceneId} 关注我们。";
        }
        
        return new TextResponseMessage(message) {
            Content = welcomeContent
        };
    }
    
    // 其他消息处理方法...
    
    // 辅助方法
    private async Task<string> GetWeatherInfoAsync()
    {
        // 模拟获取天气信息
        await Task.Delay(100);
        return "当前天气：晴朗 25°C\n紫外线指数：中等\n适合户外活动";
    }
    
    private async Task<string> GetNewsSummaryAsync()
    {
        // 模拟获取新闻摘要
        await Task.Delay(100);
        return "今日热点：\n1. 最新科技突破\n2. 经济政策更新\n3. 健康生活指南\n回复'新闻1'查看详情";
    }
    
    private async Task SaveImageToStorageAsync(string imageUrl, string mediaId)
    {
        try
        {
            // 保存图片到存储服务
            _logger.LogInformation("保存图片: {MediaId}", mediaId);
            // 实际应用中实现存储逻辑
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "保存图片失败: {MediaId}", mediaId);
        }
    }
    
    private async Task RecordUserSubscribeAsync(string openId, string eventKey)
    {
        try
        {
            // 记录用户关注信息到数据库
            _logger.LogInformation("记录用户关注: {OpenId}, EventKey: {EventKey}", openId, eventKey);
            // 实际应用中实现数据库记录逻辑
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "记录用户关注失败: {OpenId}", openId);
        }
    }
}

// 自定义消息处理器
public class CustomMessageHandler : MessageHandlerBase
{
    private readonly IWechatService _wechatService;
    private readonly IUserService _userService;
    
    public CustomMessageHandler(IWechatService wechatService, IUserService userService)
    {
        _wechatService = wechatService;
        _userService = userService;
    }
    
    [MessageHandler(MessageType.Text)]
    public async Task<ResponseMessageBase> HandleTextMessage(TextRequestMessage message)
    {
        // 根据关键词进行处理
        switch (message.Content.Trim())
        {
            case "帮助":
                return CreateHelpMessage(message);
            case "账户":
                return await CreateAccountInfoMessage(message);
            default:
                return CreateDefaultResponse(message);
        }
    }
    
    [MessageHandler(EventType.Click)]
    public async Task<ResponseMessageBase> HandleMenuClick(ClickEventMessage message)
    {
        // 处理菜单点击事件
        switch (message.EventKey)
        {
            case "MENU_ABOUT":
                return CreateAboutMessage(message);
            case "MENU_SERVICE":
                return CreateServiceListMessage(message);
            case "MENU_CONTACT":
                return CreateContactMessage(message);
            default:
                return CreateDefaultResponse(message);
        }
    }
}

微信支付示例

using Cyclops.Wechat.Models.Payment;
using Cyclops.Wechat.Services;
using Microsoft.AspNetCore.Mvc;
using System.Text.Json;

[Route("api/[controller]")]
[ApiController]
public class WechatPayController : ControllerBase
{
    private readonly IWechatPaymentService _paymentService;
    private readonly IOrderService _orderService;
    private readonly ILogger<WechatPayController> _logger;
    
    public WechatPayController(
        IWechatPaymentService paymentService, 
        IOrderService orderService,
        ILogger<WechatPayController> logger)
    {
        _paymentService = paymentService;
        _orderService = orderService;
        _logger = logger;
    }
    
    /// <summary>
    /// 创建支付订单
    /// </summary>
    [HttpPost("create-order")]
    public async Task<IActionResult> CreateOrder([FromBody] CreatePayOrderRequest request)
    {
        try
        {
            if (!ModelState.IsValid)
            {
                _logger.LogWarning("创建支付订单参数无效");
                return BadRequest(ModelState);
            }
            
            // 验证订单信息
            var order = await _orderService.GetOrderByIdAsync(request.OrderId);
            
            if (order == null)
            {
                _logger.LogWarning("订单不存在: {OrderId}", request.OrderId);
                return NotFound("订单不存在");
            }
            
            if (order.Status != OrderStatus.Pending)
            {
                _logger.LogWarning("订单状态不允许支付: {OrderId}, Status: {Status}", 
                    request.OrderId, order.Status);
                return BadRequest("订单状态不允许支付");
            }
            
            // 生成商户订单号
            var outTradeNo = $"{DateTime.Now:yyyyMMddHHmmss}{request.OrderId}{Random.Shared.Next(100, 999)}";
            
            // 创建支付订单请求
            var payRequest = new UnifyOrderRequest {
                Body = order.Title, // 商品描述
                Detail = order.Description, // 商品详情
                OutTradeNo = outTradeNo, // 商户订单号
                TotalFee = (int)(order.Amount * 100), // 订单金额（分）
                SpbillCreateIp = GetClientIp(), // 客户端IP
                NotifyUrl = $"{Request.Scheme}://{Request.Host}/api/wechatpay/notify", // 支付结果通知URL
                TradeType = TradeType.JSAPI, // 交易类型
                OpenId = request.OpenId // 用户OpenId（JSAPI支付必需）
            };
            
            // 调用统一下单API
            var payResult = await _paymentService.UnifyOrderAsync(payRequest);
            
            if (!payResult.IsSuccess)
            {
                _logger.LogError("微信支付统一下单失败: {Error}", payResult.ErrorMessage);
                await _orderService.UpdateOrderStatusAsync(request.OrderId, OrderStatus.PaymentFailed);
                return BadRequest($"创建支付订单失败: {payResult.ErrorMessage}");
            }
            
            // 更新订单支付信息
            await _orderService.UpdateOrderPaymentInfoAsync(request.OrderId, 
                payResult.TransactionId, outTradeNo, PaymentMethod.WechatPay);
            
            // 生成JSAPI支付参数
            var jsApiParameters = _paymentService.GenerateJsApiParameters(payResult.PrepayId);
            
            _logger.LogInformation("微信支付订单创建成功: {OrderId}, {OutTradeNo}", 
                request.OrderId, outTradeNo);
            
            return Ok(new {
                orderId = request.OrderId,
                paymentParameters = jsApiParameters,
                timestamp = jsApiParameters.TimeStamp,
                nonceStr = jsApiParameters.NonceStr,
                package = jsApiParameters.Package,
                signType = jsApiParameters.SignType,
                paySign = jsApiParameters.PaySign
            });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "创建微信支付订单时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    /// <summary>
    /// 支付结果通知
    /// </summary>
    [HttpPost("notify")]
    public async Task<IActionResult> PayNotify()
    {
        try
        {
            // 读取请求体
            using var reader = new StreamReader(Request.Body);
            var notifyXml = await reader.ReadToEndAsync();
            
            _logger.LogInformation("收到微信支付通知: {Xml}", notifyXml);
            
            // 解析通知数据
            var notifyResult = _paymentService.ParsePayNotifyXml(notifyXml);
            
            if (!notifyResult.IsSuccess)
            {
                _logger.LogError("解析支付通知失败: {Error}", notifyResult.ErrorMessage);
                return Content(_paymentService.GeneratePayNotifyResult(false));
            }
            
            // 验证签名
            if (!_paymentService.VerifyNotifySign(notifyResult.Parameters))
            {
                _logger.LogError("支付通知签名验证失败");
                return Content(_paymentService.GeneratePayNotifyResult(false));
            }
            
            // 处理支付结果
            var outTradeNo = notifyResult.Parameters["out_trade_no"];
            var transactionId = notifyResult.Parameters["transaction_id"];
            var totalFee = int.Parse(notifyResult.Parameters["total_fee"]);
            var resultCode = notifyResult.Parameters["result_code"];
            
            if (resultCode == "SUCCESS")
            {
                // 支付成功
                await ProcessSuccessfulPayment(outTradeNo, transactionId, totalFee / 100.0m);
                
                _logger.LogInformation("支付成功处理: {OutTradeNo}, {TransactionId}", 
                    outTradeNo, transactionId);
                
                // 返回成功响应给微信服务器
                return Content(_paymentService.GeneratePayNotifyResult(true));
            }
            else
            {
                // 支付失败
                var errCode = notifyResult.Parameters["err_code"];
                var errCodeDes = notifyResult.Parameters["err_code_des"];
                
                _logger.LogError("支付失败: {OutTradeNo}, {ErrCode}: {ErrDes}", 
                    outTradeNo, errCode, errCodeDes);
                
                // 返回成功响应（避免微信重复通知）
                return Content(_paymentService.GeneratePayNotifyResult(true));
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "处理微信支付通知时发生异常");
            return Content(_paymentService.GeneratePayNotifyResult(false));
        }
    }
    
    /// <summary>
    /// 查询订单
    /// </summary>
    [HttpGet("query-order/{orderId}")]
    public async Task<IActionResult> QueryOrder(int orderId)
    {
        try
        {
            // 获取订单信息
            var order = await _orderService.GetOrderByIdAsync(orderId);
            
            if (order == null)
            {
                return NotFound("订单不存在");
            }
            
            if (string.IsNullOrEmpty(order.TransactionId))
            {
                return BadRequest("订单未支付");
            }
            
            // 查询支付订单
            var queryResult = await _paymentService.QueryOrderAsync(order.TransactionId, order.PaymentNo);
            
            if (!queryResult.IsSuccess)
            {
                _logger.LogError("查询支付订单失败: {Error}", queryResult.ErrorMessage);
                return BadRequest($"查询支付订单失败: {queryResult.ErrorMessage}");
            }
            
            return Ok(new {
                orderId = order.Id,
                paymentNo = order.PaymentNo,
                transactionId = queryResult.TransactionId,
                tradeState = queryResult.TradeState,
                payTime = queryResult.TimeEnd,
                totalAmount = queryResult.TotalFee / 100.0m
            });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "查询微信支付订单时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    /// <summary>
    /// 申请退款
    /// </summary>
    [HttpPost("refund/{orderId}")]
    public async Task<IActionResult> RefundOrder(int orderId, [FromBody] RefundRequest request)
    {
        try
        {
            // 验证订单信息
            var order = await _orderService.GetOrderByIdAsync(orderId);
            
            if (order == null)
            {
                return NotFound("订单不存在");
            }
            
            if (order.Status != OrderStatus.Paid)
            {
                return BadRequest("订单状态不允许退款");
            }
            
            if (string.IsNullOrEmpty(order.TransactionId))
            {
                return BadRequest("订单未支付，无法退款");
            }
            
            // 生成退款单号
            var outRefundNo = $"refund{DateTime.Now:yyyyMMddHHmmss}{orderId}{Random.Shared.Next(100, 999)}";
            
            // 创建退款请求
            var refundRequest = new RefundOrderRequest {
                TransactionId = order.TransactionId,
                OutTradeNo = order.PaymentNo,
                OutRefundNo = outRefundNo,
                TotalFee = (int)(order.Amount * 100),
                RefundFee = (int)(request.Amount * 100),
                RefundDesc = request.Reason,
                NotifyUrl = $"{Request.Scheme}://{Request.Host}/api/wechatpay/refund-notify" // 退款结果通知URL
            };
            
            // 调用退款API
            var refundResult = await _paymentService.RefundAsync(refundRequest);
            
            if (!refundResult.IsSuccess)
            {
                _logger.LogError("微信支付退款失败: {Error}", refundResult.ErrorMessage);
                return BadRequest($"申请退款失败: {refundResult.ErrorMessage}");
            }
            
            // 更新订单状态
            await _orderService.ApplyRefundAsync(orderId, request.Amount, request.Reason, outRefundNo);
            
            return Ok(new {
                orderId = orderId,
                refundNo = outRefundNo,
                refundId = refundResult.RefundId,
                amount = request.Amount,
                status = "REFUND_PROCESSING"
            });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "申请微信支付退款时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    // 辅助方法
    private string GetClientIp()
    {
        return Request.HttpContext.Connection.RemoteIpAddress.ToString();
    }
    
    private async Task ProcessSuccessfulPayment(string outTradeNo, string transactionId, decimal amount)
    {
        // 查找订单
        var order = await _orderService.GetOrderByPaymentNoAsync(outTradeNo);
        
        if (order != null && order.Status == OrderStatus.Pending)
        {
            // 更新订单状态为已支付
            await _orderService.UpdateOrderStatusAsync(order.Id, OrderStatus.Paid);
            
            // 触发订单支付成功事件
            await _orderService.TriggerOrderPaidEventAsync(order.Id);
            
            // 发送支付成功通知
            await SendPaymentSuccessNotificationAsync(order.Id, order.UserId);
        }
    }
    
    private async Task SendPaymentSuccessNotificationAsync(int orderId, int userId)
    {
        try
        {
            // 发送模板消息通知用户
            var templateData = new Dictionary<string, TemplateDataItem> {
                { "first", new TemplateDataItem { Value = "您的订单支付成功！" } },
                { "keyword1", new TemplateDataItem { Value = $"订单#{orderId}" } },
                { "keyword2", new TemplateDataItem { Value = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss") } },
                { "remark", new TemplateDataItem { Value = "感谢您的购买，祝您使用愉快！" } }
            };
            
            // 获取用户OpenId
            var user = await _userService.GetUserByIdAsync(userId);
            if (!string.IsNullOrEmpty(user.WechatOpenId))
            {
                await _wechatService.SendTemplateMessageAsync(
                    user.WechatOpenId,
                    "templateId", // 替换为实际的模板ID
                    $"{Request.Scheme}://{Request.Host}/order/detail/{orderId}",
                    templateData
                );
            }
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "发送支付成功通知失败: {OrderId}", orderId);
        }
    }
}

// 请求模型
public class CreatePayOrderRequest
{
    [Required]
    public int OrderId { get; set; }
    
    [Required]
    public string OpenId { get; set; }
}

public class RefundRequest
{
    [Required]
    [Range(0.01, double.MaxValue)]
    public decimal Amount { get; set; }
    
    [Required]
    [StringLength(200)]
    public string Reason { get; set; }
}

// 订单服务接口
public interface IOrderService
{
    Task<Order> GetOrderByIdAsync(int orderId);
    Task<Order> GetOrderByPaymentNoAsync(string paymentNo);
    Task<bool> UpdateOrderStatusAsync(int orderId, OrderStatus status);
    Task<bool> UpdateOrderPaymentInfoAsync(int orderId, string transactionId, string paymentNo, PaymentMethod method);
    Task<bool> ApplyRefundAsync(int orderId, decimal amount, string reason, string refundNo);
    Task TriggerOrderPaidEventAsync(int orderId);
}

public enum OrderStatus
{
    Pending,
    Paid,
    Shipped,
    Completed,
    Cancelled,
    PaymentFailed,
    Refunded
}

public enum PaymentMethod
{
    WechatPay,
    Alipay,
    BankTransfer
}

public class Order
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public decimal Amount { get; set; }
    public OrderStatus Status { get; set; }
    public string PaymentNo { get; set; }
    public string TransactionId { get; set; }
    public PaymentMethod? PaymentMethod { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime UpdatedAt { get; set; }
    public int UserId { get; set; }
}

微信小程序示例

using Cyclops.Wechat.Models.Miniprogram;
using Cyclops.Wechat.Services;
using Microsoft.AspNetCore.Mvc;

[Route("api/[controller]")]
[ApiController]
public class MiniprogramController : ControllerBase
{
    private readonly IWechatMiniprogramService _miniprogramService;
    private readonly ILogger<MiniprogramController> _logger;
    
    public MiniprogramController(IWechatMiniprogramService miniprogramService, ILogger<MiniprogramController> logger)
    {
        _miniprogramService = miniprogramService;
        _logger = logger;
    }
    
    /// <summary>
    /// 生成小程序码
    /// </summary>
    [HttpGet("generate-qrcode")]
    public async Task<IActionResult> GenerateQrcode([FromQuery] string scene, [FromQuery] string page = "pages/index/index", [FromQuery] int width = 430)
    {
        try
        {
            if (string.IsNullOrEmpty(scene))
            {
                return BadRequest("场景值不能为空");
            }
            
            // 调用生成小程序码API
            var qrcodeResult = await _miniprogramService.CreateWxaQrcodeAsync(new WxaQrcodeRequest {
                Scene = scene,
                Page = page,
                Width = width,
                AutoColor = true,
                LineColor = new { r = 0, g = 0, b = 0 },
                IsHyaline = false
            });
            
            if (!qrcodeResult.IsSuccess)
            {
                _logger.LogError("生成小程序码失败: {Error}", qrcodeResult.ErrorMessage);
                return BadRequest($"生成小程序码失败: {qrcodeResult.ErrorMessage}");
            }
            
            // 返回图片流
            Response.ContentType = "image/png";
            return File(qrcodeResult.ImageData, "image/png");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "生成小程序码时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    /// <summary>
    /// 发送订阅消息
    /// </summary>
    [HttpPost("send-subscribe-message")]
    public async Task<IActionResult> SendSubscribeMessage([FromBody] SubscribeMessageRequest request)
    {
        try
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            
            // 构建订阅消息数据
            var data = new Dictionary<string, SubscribeMessageData> {
                { "thing1", new SubscribeMessageData { Value = request.OrderTitle } },
                { "time2", new SubscribeMessageData { Value = request.OrderTime } },
                { "amount3", new SubscribeMessageData { Value = request.Amount } },
                { "thing4", new SubscribeMessageData { Value = request.Message } },
                { "thing5", new SubscribeMessageData { Value = request.Remarks } }
            };
            
            // 发送订阅消息
            var sendResult = await _miniprogramService.SendSubscribeMessageAsync(new SendSubscribeMessageRequest {
                ToUser = request.OpenId,
                TemplateId = request.TemplateId,
                Page = request.Page,
                Data = data
            });
            
            if (!sendResult.IsSuccess)
            {
                _logger.LogError("发送订阅消息失败: {Error}", sendResult.ErrorMessage);
                return BadRequest($"发送消息失败: {sendResult.ErrorMessage}");
            }
            
            return Ok(new { message = "消息发送成功" });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "发送订阅消息时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    /// <summary>
    /// 小程序登录验证
    /// </summary>
    [HttpPost("login")]
    public async Task<IActionResult> MiniprogramLogin([FromBody] MiniprogramLoginRequest request)
    {
        try
        {
            if (string.IsNullOrEmpty(request.Code))
            {
                return BadRequest("登录凭证不能为空");
            }
            
            // 调用登录凭证校验接口
            var loginResult = await _miniprogramService.LoginAsync(request.Code);
            
            if (!loginResult.IsSuccess)
            {
                _logger.LogError("小程序登录校验失败: {Error}", loginResult.ErrorMessage);
                return BadRequest($"登录失败: {loginResult.ErrorMessage}");
            }
            
            // 获取用户唯一标识
            var openId = loginResult.OpenId;
            var unionId = loginResult.UnionId;
            
            // 处理用户登录逻辑
            var userInfo = await ProcessMiniprogramLoginAsync(openId, unionId, request.UserInfo);
            
            // 生成JWT令牌
            var token = GenerateJwtToken(userInfo);
            
            return Ok(new {
                token = token,
                user = new {
                    id = userInfo.Id,
                    nickname = userInfo.Nickname,
                    avatar = userInfo.Avatar
                }
            });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "小程序登录时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    /// <summary>
    /// 内容安全检测
    /// </summary>
    [HttpPost("security-check")]
    public async Task<IActionResult> SecurityCheck([FromBody] SecurityCheckRequest request)
    {
        try
        {
            if (string.IsNullOrEmpty(request.Content))
            {
                return BadRequest("检测内容不能为空");
            }
            
            // 调用内容安全检测API
            var checkResult = await _miniprogramService.SecurityCheckAsync(request.Content);
            
            if (!checkResult.IsSuccess)
            {
                _logger.LogWarning("内容安全检测失败: {Content}", request.Content);
                return BadRequest(new {
                    pass = false,
                    reason = "内容包含敏感信息，不允许发布"
                });
            }
            
            return Ok(new {
                pass = true
            });
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "内容安全检测时发生异常");
            return StatusCode(500, "服务器内部错误");
        }
    }
    
    // 辅助方法
    private async Task<UserInfo> ProcessMiniprogramLoginAsync(string openId, string unionId, UserInfoRequest userInfo)
    {
        // 查找或创建用户
        var existingUser = await GetUserByOpenIdAsync(openId);
        
        if (existingUser != null)
        {
            // 更新用户信息
            if (!string.IsNullOrEmpty(unionId) && existingUser.UnionId != unionId)
            {
                existingUser.UnionId = unionId;
            }
            
            if (userInfo != null)
            {
                existingUser.Nickname = userInfo.NickName;
                existingUser.Avatar = userInfo.AvatarUrl;
                existingUser.Gender = userInfo.Gender;
                existingUser.Country = userInfo.Country;
                existingUser.Province = userInfo.Province;
                existingUser.City = userInfo.City;
                existingUser.Language = userInfo.Language;
            }
            
            await UpdateUserAsync(existingUser);
            return existingUser;
        }
        else
        {
            // 创建新用户
            var newUser = new UserInfo {
                OpenId = openId,
                UnionId = unionId,
                Nickname = userInfo?.NickName,
                Avatar = userInfo?.AvatarUrl,
                Gender = userInfo?.Gender ?? 0,
                Country = userInfo?.Country,
                Province = userInfo?.Province,
                City = userInfo?.City,
                Language = userInfo?.Language,
                CreatedAt = DateTime.Now,
                LastLoginAt = DateTime.Now
            };
            
            await CreateUserAsync(newUser);
            return newUser;
        }
    }
    
    private string GenerateJwtToken(UserInfo userInfo)
    {
        // 生成JWT令牌的实现
        // 这里省略具体实现
        return "sample-jwt-token";
    }
    
    // 模拟数据库操作
    private Task<UserInfo> GetUserByOpenIdAsync(string openId) => Task.FromResult<UserInfo>(null);
    private Task UpdateUserAsync(UserInfo user) => Task.CompletedTask;
    private Task CreateUserAsync(UserInfo user) => Task.CompletedTask;
}

// 请求模型
public class SubscribeMessageRequest
{
    [Required]
    public string OpenId { get; set; }
    
    [Required]
    public string TemplateId { get; set; }
    
    public string Page { get; set; }
    
    [Required]
    public string OrderTitle { get; set; }
    
    [Required]
    public string OrderTime { get; set; }
    
    [Required]
    public string Amount { get; set; }
    
    [Required]
    public string Message { get; set; }
    
    public string Remarks { get; set; }
}

public class MiniprogramLoginRequest
{
    [Required]
    public string Code { get; set; }
    
    public UserInfoRequest UserInfo { get; set; }
}

public class UserInfoRequest
{
    public string NickName { get; set; }
    public string AvatarUrl { get; set; }
    public int Gender { get; set; }
    public string Country { get; set; }
    public string Province { get; set; }
    public string City { get; set; }
    public string Language { get; set; }
}

public class SecurityCheckRequest
{
    [Required]
    public string Content { get; set; }
}

public class UserInfo
{
    public int Id { get; set; }
    public string OpenId { get; set; }
    public string UnionId { get; set; }
    public string Nickname { get; set; }
    public string Avatar { get; set; }
    public int Gender { get; set; }
    public string Country { get; set; }
    public string Province { get; set; }
    public string City { get; set; }
    public string Language { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime LastLoginAt { get; set; }
}

版本信息

• 当前版本
• 作者：yswenli
• 描述：企服版框架中微信集成组件

贡献者

• yswenli

许可证

保留所有权利