invest-research-backend/src/main/java/com/nylc/touyan/datasource/DataSourceClient.java

package com.nylc.touyan.datasource;

import java.io.Closeable;
import java.util.List;
import java.util.Map;

/**
 * 统一的数据源客户端抽象。
 * 业务层只依赖该接口，不关心底层是 SQLite / MySQL / 其他。
 *
 * 设计原则：
 * 1. 入参/出参使用基础类型（String SQL + Object... params + List<Map>），保持通用；
 * 2. 各实现自行保证线程安全与连接管理；
 * 3. 新增数据源只需实现本接口并在 {@link DataSourceFactory} 注册。
 */
public interface DataSourceClient extends Closeable {

    /** 当前数据源类型标识，用于日志/诊断。 */
    String type();

    /** 健康检查：连接可用返回 true。 */
    boolean ping();

    /** 查询列表；无结果返回空集合（不返回 null）。 */
    List<Map<String, Object>> queryForList(String sql, Object... params);

    /** 查询单条；无结果返回 null。 */
    Map<String, Object> queryForMap(String sql, Object... params);

    /** 单标量查询（例如 SELECT COUNT(*) / SELECT NOW()），无结果返回 null。 */
    Object queryForObject(String sql, Object... params);

    /** 执行 INSERT/UPDATE/DELETE，返回受影响行数。 */
    int update(String sql, Object... params);

    /** 批量执行同结构 SQL，返回每条受影响行数。 */
    int[] batchUpdate(String sql, List<Object[]> paramsBatch);

    /** 执行任意 SQL（DDL 等），无返回结果。 */
    void execute(String sql);
}