参考资料

https://github.com/junkai-li/NetCoreKevin

https://gitee.com/netkevin-li/NetCoreKevin

API v1端点

执行摘要

本文档详细描述了 NetCoreKevin 项目的 API v1 端点，包括 PayController、SignController 和 UserController 的功能、使用场景及认证要求。系统支持微信和支付宝支付、用户管理、标记功能等多种业务场景，大多数接口需要 Token 认证，支持多种登录方式。

系统架构

系统采用分层架构设计，API 端点通过控制器实现，依赖于服务层和数据访问层。核心控制器包括支付、标记和用户管理模块，与微信和支付宝等第三方服务集成。

核心组件

PayController

• 描述：处理第三方支付相关操作，支持微信和支付宝支付。
• 端点详情：
  1. GET api/Pay/CreateWeiXinMiniAppPay
     • 参数：orderno (string), weixinkeyid (Guid)
     • 返回：dtoCreatePayMiniApp
     • 功能：创建微信小程序支付订单。
     • 请求示例：GET /api/Pay/CreateWeiXinMiniAppPay?orderno=123456&weixinkeyid=guid-value
     • 响应示例：{ "appId": "wx123", "timeStamp": "1234567890", "nonceStr": "randomstr", "package": "prepay_id=wx123", "signType": "MD5", "paySign": "signature" }
  2. POST api/Pay/WeiXinPayNotify
     • 参数：无（接收微信回调数据）
     • 返回：XML 格式字符串
     • 功能：处理微信支付异步通知，更新订单状态。
     • 请求示例：微信支付平台回调数据
     • 响应示例：<xml><return_code><![CDATA[SUCCESS]]></return_code><return_msg><![CDATA[OK]]></return_msg></xml>

SignController

• 描述：处理标记相关操作，如点赞或收藏。
• 端点详情：
  1. GET api/Sign/GetSignCount
     • 参数：table (string), tableId (Guid), sign (string)
     • 返回：int
     • 功能：获取特定表和 ID 的标记总数。
     • 请求示例：GET /api/Sign/GetSignCount?table=article&tableId=guid-value&sign=like
     • 响应示例：10
  2. POST api/Sign/AddSign
     • 参数：addSign (dtoSign)
     • 返回：bool
     • 功能：新增标记。
     • 请求示例：POST /api/Sign/AddSign { "table": "article", "tableId": "guid-value", "sign": "like" }
     • 响应示例：true

UserController

• 描述：处理用户数据操作，包括用户信息查询和修改。
• 端点详情：
  1. GET api/User/GetWeiXinMiniAppOpenId
     • 参数：weixinkeyid (Guid), code (string)
     • 返回：string
     • 功能：获取微信小程序 OpenId。
     • 请求示例：GET /api/User/GetWeiXinMiniAppOpenId?weixinkeyid=guid-value&code=code-value
     • 响应示例："openid-value,userid-value"
  2. GET api/User/GetUser
     • 参数：userId (Guid)
     • 返回：dtoUser
     • 功能：通过 UserId 获取用户信息。
     • 请求示例：GET /api/User/GetUser?userId=guid-value
     • 响应示例：{ "id": "guid-value", "name": "username", "phone": "12345678901" }

实现模式

系统采用 RESTful API 设计风格，使用 HTTP 方法区分操作类型（如 GET 查询，POST 创建）。控制器依赖注入服务层实现业务逻辑，数据访问层使用 Entity Framework Core 进行数据库操作。认证基于 JWT Token，通过 AuthorizeController 提供多种登录方式。

数据流

数据流从用户请求到 API 端点，再到服务层和数据库，最后返回响应。支付相关端点还涉及与第三方支付平台的交互。

集成点

• 微信支付：通过 Web.Libraries.WeiXin 库与微信支付平台集成，支持小程序、APP 和网页支付。
• 支付宝支付：通过 AliPayHelper 与支付宝支付平台集成，支持小程序和网页支付。
• 认证服务：通过 AuthorizeController 提供 Token 认证，支持用户名密码、微信 Code 和短信验证码登录。

性能分析

• 缓存机制：部分接口如 GetUser 使用缓存过滤器 [CacheDataFilter]，提高查询性能。
• 优化建议：支付回调接口应确保高可用性，避免单点故障；数据库查询可进一步优化索引以提高性能。

故障排除指南

• 支付失败：检查订单号是否正确，支付密钥是否配置正确，网络是否通畅。
• Token 失效：重新调用 GetToken 接口获取新 Token，确保请求头包含有效 Authorization 信息。
• 接口返回 401：检查是否缺少认证信息或 Token 已过期。
• 接口返回 403：检查用户是否有权限访问该接口，部分接口可能需要特定角色。

参考文献