|
|
// ============================================================================
|
|
|
// 【文件说明】IHwSearchSchemaService.cs - 搜索表结构服务接口
|
|
|
// ============================================================================
|
|
|
// 这个接口定义了搜索表结构初始化的契约。
|
|
|
//
|
|
|
// 【为什么需要接口？】
|
|
|
// 1. 依赖倒置原则（DIP）：高层模块依赖抽象，不依赖具体实现
|
|
|
// 2. 便于测试：可以 Mock 这个接口进行单元测试
|
|
|
// 3. 便于扩展：未来可以有不同的实现（如支持 PostgreSQL）
|
|
|
//
|
|
|
// 【与 Java Spring Boot 的对比】
|
|
|
// Java Spring Boot:
|
|
|
// public interface IHwSearchSchemaService {
|
|
|
// CompletableFuture<Void> ensureCreatedAsync();
|
|
|
// }
|
|
|
//
|
|
|
// C# ASP.NET Core:
|
|
|
// public interface IHwSearchSchemaService {
|
|
|
// Task EnsureCreatedAsync(CancellationToken cancellationToken = default);
|
|
|
// }
|
|
|
//
|
|
|
// 两者概念完全一样，只是异步返回类型不同：
|
|
|
// - Java 用 CompletableFuture
|
|
|
// - C# 用 Task
|
|
|
// ============================================================================
|
|
|
|
|
|
namespace Admin.NET.Plugin.HwPortal;
|
|
|
|
|
|
/// <summary>
|
|
|
/// 搜索表结构服务接口。
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - 接口定义】
|
|
|
/// public interface IHwSearchSchemaService
|
|
|
///
|
|
|
/// 接口定义了一组方法签名，不包含实现：
|
|
|
/// - 只声明方法，不实现方法
|
|
|
/// - 实现类必须提供所有方法的具体实现
|
|
|
///
|
|
|
/// 对比 Java：
|
|
|
/// Java 的接口语法完全一样：
|
|
|
/// public interface IHwSearchSchemaService {
|
|
|
/// void ensureCreatedAsync();
|
|
|
/// }
|
|
|
///
|
|
|
/// 【命名约定】
|
|
|
/// C# 接口命名约定：I + PascalCase
|
|
|
/// - IHwSearchSchemaService：I 前缀表示 Interface
|
|
|
/// - HwSearchSchemaService：实现类不加 I 前缀
|
|
|
///
|
|
|
/// Java 接口命名约定：不加 I 前缀
|
|
|
/// - HwSearchSchemaService：接口
|
|
|
/// - HwSearchSchemaServiceImpl：实现类
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
public interface IHwSearchSchemaService
|
|
|
{
|
|
|
/// <summary>
|
|
|
/// 确保搜索表已创建。
|
|
|
/// <para>
|
|
|
/// 【方法语义】
|
|
|
/// "Ensure" 表示"确保"，是一种幂等操作：
|
|
|
/// - 如果表已存在，不做任何操作
|
|
|
/// - 如果表不存在，创建表
|
|
|
///
|
|
|
/// 对比 "Create"：
|
|
|
/// - Create：每次都创建，重复调用会报错
|
|
|
/// - EnsureCreated：幂等，可以安全地多次调用
|
|
|
/// </para>
|
|
|
/// <para>
|
|
|
/// 【C# 语法知识点 - CancellationToken 参数】
|
|
|
/// CancellationToken cancellationToken = default
|
|
|
///
|
|
|
/// 这是 C# 异步编程的标准模式：
|
|
|
/// - CancellationToken：取消令牌，用于取消长时间运行的操作
|
|
|
/// - = default：默认值，调用时可以不传
|
|
|
///
|
|
|
/// 使用场景：
|
|
|
/// 1. 用户取消请求：浏览器关闭或刷新
|
|
|
/// 2. 超时取消：操作超过指定时间
|
|
|
/// 3. 应用关闭：服务器需要优雅关闭
|
|
|
///
|
|
|
/// 对比 Java：
|
|
|
/// Java 没有内置的取消机制，通常用自定义标志位：
|
|
|
/// private volatile boolean cancelled = false;
|
|
|
/// public void cancel() { cancelled = true; }
|
|
|
///
|
|
|
/// C# 的 CancellationToken 是框架级支持，更优雅。
|
|
|
/// </para>
|
|
|
/// </summary>
|
|
|
/// <param name="cancellationToken">取消令牌</param>
|
|
|
/// <returns>异步任务</returns>
|
|
|
Task EnsureCreatedAsync(CancellationToken cancellationToken = default);
|
|
|
}
|