增加初始化类文件
|
# NewLife.WeChat 项目创建指南（Claude AI）
本文档用于指导 AI 助手（如 Claude）创建标准的 NewLife 系列工具类库项目。
## 项目概述
**项目名称**: NewLife.WeChat
**项目类型**: .NET 类库
**目标框架**: .NET 10
**主要功能**: 微信开发工具类库，提供公众号、小程序等功能支持
**依赖框架**: NewLife.Core、NewLife.XCode
## 技术栈要求
### 核心依赖
```xml
<PackageReference Include="NewLife.Core" Version="*" />
<PackageReference Include="NewLife.XCode" Version="*" />
```
### 开发环境
- .NET SDK 10.0+
- C# 14.0
- Visual Studio 2024 或 VS Code
- 支持 ImplicitUsings 和 Nullable
## 项目结构设计
```
NewLife.WeChat/
├── Entities/ # XCode 实体模型层
│ ├── Model.xml # XCode 模型定义文件
│ ├── 微信配置.cs # 实体定义（自动生成）
│ └── 微信配置.Biz.cs # 业务逻辑扩展（手动编写）
│
├── Services/ # 服务层
│ ├── WeChatService.cs # 微信核心服务
│ └── ApiClient.cs # API 客户端（可选）
│
├── Models/ # 数据模型层
│ ├── WeChatModels.cs # 基础模型
│ ├── Messages.cs # 消息模型
│ ├── Request/ # 请求模型（可选）
│ └── Response/ # 响应模型（可选）
│
├── Utils/ # 工具类
│ ├── SignHelper.cs # 签名辅助类
│ └── CryptoHelper.cs # 加密辅助类
│
├── docs/ # 文档
│ ├── Architecture.md # 架构设计文档
│ └── QuickStart.md # 快速开始指南
│
├── GlobalUsings.cs # 全局 using 声明
├── WeChatManager.cs # 管理器类（可选）
├── README.md # 项目说明
└── NewLife.WeChat.csproj # 项目文件
```
## 代码规范
### 命名约定
1. **实体类**: 使用中文命名（符合 XCode 规范）
- 示例: `微信配置`, `微信用户`, `微信消息`
2. **服务类**: 使用英文 + Service 后缀
- 示例: `WeChatService`, `TokenService`, `MessageService`
3. **工具类**: 使用英文 + Helper 后缀
- 示例: `SignHelper`, `CryptoHelper`, `XmlHelper`
4. **模型类**: 使用英文描述性名称
- 示例: `AccessTokenResponse`, `WeChatMessage`, `TextMessage`
### 文件头注释
```csharp
/// <summary>类功能描述</summary>
public class ClassName
{
// 实现代码
}
```
### 属性注释
```csharp
/// <summary>属性描述</summary>
[DisplayName("属性显示名")]
[Description("详细描述")]
public String PropertyName { get; set; }
```
## XCode 实体模型设计
### Model.xml 结构
```xml
<?xml version="1.0" encoding="utf-8"?>
<Tables Version="11.0.2024.1101"
Output="Entities"
NameSpace="项目命名空间.Entities"
ConnName="连接名"
BaseClass="Entity">
<Table Name="表名" Description="表描述" DbType="SqlServer">
<Columns>
<Column Name="Id" DataType="Int32" Identity="True" PrimaryKey="True" Description="编号" />
<!-- 更多字段 -->
</Columns>
<Indexes>
<Index Columns="字段名" Unique="True" />
</Indexes>
</Table>
</Tables>
```
### 实体类要求
1. **基础属性**
- Id: 主键，Int32，自增
- CreateTime: 创建时间
- UpdateTime: 更新时间
- Remark: 备注
2. **索引设计**
- 唯一索引：业务主键（如 AppId）
- 普通索引：查询频繁的字段（如 IsEnabled）
3. **业务扩展** (*.Biz.cs)
```csharp
public partial class 实体名 : Entity<实体名>
{
#region 对象操作
static 实体名()
{
// 过滤器
Meta.Modules.Add<TimeModule>();
Meta.Modules.Add<IPModule>();
// 单对象缓存
var sc = Meta.SingleCache;
sc.FindSlaveKeyMethod = k => Find(_.唯一字段 == k);
sc.GetSlaveKeyMethod = e => e.唯一字段;
}
public override void Valid(Boolean isNew)
{
base.Valid(isNew);
// 数据验证逻辑
}
#endregion
#region 扩展查询
public static 实体名 FindByXxx(参数类型 参数) { }
#endregion
#region 业务操作
// 业务方法
#endregion
}
```
## 服务层设计
### WeChatService 模板
```csharp
public class WeChatService
{
private readonly 配置实体 _config;
private readonly HttpClient _httpClient;
private static readonly ILog _log = XTrace.Log;
public const String ApiBaseUrl = "https://api.weixin.qq.com";
public WeChatService(配置实体 config) { }
public WeChatService(String appId) { }
// AccessToken 管理
public async Task<String> GetAccessTokenAsync(Boolean forceRefresh = false) { }
public async Task<String> RefreshAccessTokenAsync() { }
// 通用请求
public async Task<T> GetAsync<T>(String url, Boolean includeToken = true) { }
public async Task<T> PostAsync<T>(String url, Object data, Boolean includeToken = true) { }
}
```
### 服务层原则
1. **依赖注入**: 支持构造函数注入配置
2. **异步优先**: 所有 I/O 操作使用 async/await
3. **异常处理**: 使用 try-catch 并记录日志
4. **缓存管理**: 使用 NewLife.Caching
5. **日志记录**: 使用 XTrace.Log
## 工具类设计
### SignHelper 要求
```csharp
public static class SignHelper
{
/// <summary>SHA1签名</summary>
public static String SHA1(String data) { }
/// <summary>签名验证</summary>
public static Boolean Verify(参数...) { }
/// <summary>生成随机字符串</summary>
public static String GenerateNonceStr(Int32 length = 16) { }
/// <summary>生成时间戳</summary>
public static String GenerateTimeStamp() { }
}
```
### CryptoHelper 要求
```csharp
public static class CryptoHelper
{
/// <summary>MD5加密</summary>
public static String MD5(String data) { }
/// <summary>AES加密</summary>
public static String AESEncrypt(String data, String key, String iv = null) { }
/// <summary>AES解密</summary>
public static String AESDecrypt(String data, String key, String iv = null) { }
/// <summary>Base64编码</summary>
public static String Base64Encode(String data) { }
/// <summary>Base64解码</summary>
public static String Base64Decode(String data) { }
}
```
## 模型层设计
### 基础模型
```csharp
/// <summary>API响应基类</summary>
public class WeChatResponse
{
public Int32 ErrCode { get; set; }
public String ErrMsg { get; set; }
public Boolean IsSuccess => ErrCode == 0;
}
/// <summary>具体响应</summary>
public class XxxResponse : WeChatResponse
{
// 业务字段
}
```
### 枚举定义
```csharp
/// <summary>枚举描述</summary>
public enum EnumName
{
/// <summary>选项1</summary>
Option1 = 1,
/// <summary>选项2</summary>
Option2 = 2
}
```
## 文档要求
### README.md 必须包含
1. **项目简介**: 一句话描述
2. **功能特性**: 列表形式
3. **快速开始**: 安装、配置、使用示例
4. **项目结构**: 目录树
5. **数据库支持**: 列表说明
6. **依赖项**: 链接到相关项目
7. **开发计划**: 带复选框的任务列表
8. **联系方式**: 官网、QQ群、源码地址
### Architecture.md 必须包含
1. **项目概述**
2. **技术栈**
3. **整体架构**: 目录结构
4. **核心模块**: 详细说明每个模块
5. **数据流程**: 流程图或文字描述
6. **配置管理**
7. **扩展性设计**
8. **功能模块**: 分阶段开发计划
9. **数据库设计**
10. **性能优化**
11. **安全性**
### QuickStart.md 必须包含
1. **配置数据库连接**: 多种数据库示例
2. **初始化数据表**
3. **创建配置**
4. **使用服务**: 完整代码示例
5. **完整示例**: ASP.NET Core 示例
6. **常见问题**: FAQ
## 项目文件配置
### .csproj 标准结构
```xml
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<LangVersion>latest</LangVersion>
<OutputType>Library</OutputType>
<AssemblyTitle>项目标题</AssemblyTitle>
<Description>项目描述</Description>
<Company>NewLife</Company>
<Copyright>Copyright © NewLife 2024</Copyright>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="NewLife.Core" Version="*" />
<PackageReference Include="NewLife.XCode" Version="*" />
</ItemGroup>
</Project>
```
### GlobalUsings.cs
```csharp
// 全局 Using 声明
global using System;
global using NewLife;
```
## 缓存策略
### AccessToken 缓存
```csharp
public void SetAccessToken(String token, Int32 expireSeconds = 7200)
{
var cache = NewLife.Caching.Cache.Default;
var key = GetAccessTokenCacheKey();
// 提前5分钟过期
cache.Set(key, token, expireSeconds - 300);
}
public String GetAccessToken()
{
var cache = NewLife.Caching.Cache.Default;
var key = GetAccessTokenCacheKey();
return cache.Get<String>(key);
}
```
### 实体缓存
```csharp
// 单对象缓存
var config = 实体类.FindById(id); // 自动使用缓存
// 批量查询缓存
var list = 实体类.FindAllEnabled(); // 根据需要缓存
```
## 日志记录
### 使用 XTrace
```csharp
private static readonly ILog _log = XTrace.Log;
// 信息日志
_log.Info("操作成功: {0}", message);
// 警告日志
_log.Warn("警告信息: {0}", warning);
// 错误日志
_log.Error("错误: {0}", ex.Message);
// 调试日志
_log.Debug("调试信息: {0}", debug);
```
## 异常处理
### 标准异常处理
```csharp
public async Task<T> MethodAsync()
{
try
{
// 业务逻辑
return result;
}
catch (Exception ex)
{
_log.Error($"操作失败: {ex.Message}");
throw; // 或返回默认值
}
}
```
## 单元测试建议
### 测试项目结构
```
NewLife.WeChat.Tests/
├── Entities/
│ └── 微信配置Tests.cs
├── Services/
│ └── WeChatServiceTests.cs
└── Utils/
├── SignHelperTests.cs
└── CryptoHelperTests.cs
```
### 测试用例示例
```csharp
[TestClass]
public class WeChatServiceTests
{
[TestMethod]
public async Task GetAccessTokenAsync_Success()
{
// Arrange
var service = new WeChatService("test_appid");
// Act
var token = await service.GetAccessTokenAsync();
// Assert
Assert.IsNotNull(token);
}
}
```
## 部署说明
### NuGet 打包
```xml
<PropertyGroup>
<PackageId>NewLife.WeChat</PackageId>
<Version>1.0.0</Version>
<Authors>NewLife</Authors>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageProjectUrl>https://git.newlifex.com/NewLife/NewLife.WeChat</PackageProjectUrl>
<RepositoryUrl>https://git.newlifex.com/NewLife/NewLife.WeChat</RepositoryUrl>
<PackageTags>wechat;微信;newlife</PackageTags>
</PropertyGroup>
```
### 发布命令
```bash
dotnet pack -c Release
dotnet nuget push bin/Release/NewLife.WeChat.*.nupkg -s https://nuget.newlifex.com/v3/index.json
```
## 版本管理
### 语义化版本
- **主版本号**: 不兼容的 API 修改
- **次版本号**: 向下兼容的功能性新增
- **修订号**: 向下兼容的问题修正
示例: `1.2.3`
- 1: 主版本
- 2: 次版本
- 3: 修订版本
## Git 提交规范
### Commit Message 格式
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Type 类型
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建/工具
### 示例
```
feat(entities): 添加微信配置实体模型
- 创建微信配置表结构
- 实现业务逻辑扩展
- 添加缓存支持
Closes #1
```
## AI 创建项目的步骤
### 第1步: 创建项目文件
```
NewLife.WeChat.csproj
GlobalUsings.cs
```
### 第2步: 创建实体模型
```
Entities/Model.xml
Entities/微信配置.cs
Entities/微信配置.Biz.cs
```
### 第3步: 创建服务层
```
Services/WeChatService.cs
```
### 第4步: 创建工具类
```
Utils/SignHelper.cs
Utils/CryptoHelper.cs
```
### 第5步: 创建模型
```
Models/WeChatModels.cs
Models/Messages.cs
```
### 第6步: 创建管理器
```
WeChatManager.cs
```
### 第7步: 创建文档
```
README.md
docs/Architecture.md
docs/QuickStart.md
```
### 第8步: 验证编译
```bash
dotnet restore
dotnet build
```
## 质量检查清单
- [ ] 所有类和方法都有 XML 注释
- [ ] 实体模型有对应的 Model.xml
- [ ] 服务层支持异步操作
- [ ] 工具类都是静态类
- [ ] 异常有适当的处理和日志
- [ ] 缓存策略已实现
- [ ] README.md 完整
- [ ] Architecture.md 详细
- [ ] QuickStart.md 有示例
- [ ] 项目可以成功编译
## 参考资源
- NewLife.Core: https://github.com/NewLifeX/X
- XCode 教程: https://newlifex.com/xcode
- 微信开发文档: https://developers.weixin.qq.com/doc/
---
**文档版本**: 1.0
**更新时间**: 2024-01
**维护者**: NewLife 开发团队
|