接收原生SQL的通用.NET API为何属于不良设计？

我们有一个为多个应用处理所有请求的单一.NET API，该API使用System.Data.SqlClient直接连接数据库，未借助Entity Framework这类“桥接层”。它的所有端点都是字面意义上的通用型：仅包含Get()、UpdateInsert()和Delete()三个端点，HTTP请求中需要传入完整的SQL查询语句及参数列表。编写该API的开发人员经验相对不足，更熟悉SQL连接器而非EF。虽然所有查询都已参数化，不存在SQL注入风险，但这类设计存在诸多问题。

示例代码 #

public static ReturnedObject Upsert(string sql, Dictionary<string,string> parameters, int applicationID)
{
    SqlConnection connection = new SqlConnection(ConnectionStringProvider.Retrieve(applicationID));
                
    connection.Open();

    string valueToReturn = "";
                
    try
    {
        using (SqlCommand cmd = new SqlCommand(sql, connection))
        {
            try
            {
                foreach (KeyValuePair<string,string> valuePair in parameters)
                {
                    cmd.Parameters.AddWithValue(valuePair.Key, valuePair.Value);
                }

                object result = cmd.ExecuteScalar();
                            
                if (result!=null)
                {
                    // Assign result to valueToReturn
                }
            }
            catch (Exception ex)
            {
                // Assign exception to valueToReturn
            }
        }
    }
    catch (Exception ex)
    {
        // Assign exception to valueToReturn
    }

    // Return valueToReturn
}

已识别的设计问题 #

• 违反单一职责原则：一个API承担了所有应用的数据访问逻辑，既没有按业务域拆分，也没有区分不同应用的职责边界。
• 原生SQL暴露数据库实现细节：HTTP请求中传输原生SQL，不仅让客户端直接感知到数据库表结构、字段等内部实现，还存在潜在安全风险（比如权限控制失效时，恶意客户端可执行任意合法SQL操作）。
• 数据库实现固化：直接依赖SqlClient，后续切换数据库（如从SQL Server到PostgreSQL）时，需要大量修改核心代码，迁移成本极高。
• 不利于客户端架构规范：客户端被迫在业务代码中编写原生SQL，无法遵循分层架构（如将数据访问层封装在客户端内部），导致客户端代码耦合度高、难以维护。

补充的设计缺陷 #

• 缺乏请求校验与权限管控：
  • 未对传入的SQL做业务合法性校验，比如某个客户端可能执行不属于自身业务范围的SQL（如操作其他应用的数据库表），仅靠applicationID获取连接串不足以完全隔离不同应用的数据权限。
  • 没有细粒度权限控制，无法限制客户端只能执行查询类SQL，还是可以执行修改/删除类操作，一旦连接串对应的数据库账号权限过大，风险极高。
• 错误处理与日志缺失：
  • 示例代码仅将异常信息赋值给返回值，无完善的日志记录，难以排查线上问题（比如无法定位是哪个客户端执行了哪条SQL导致报错）。
  • 异常处理过于粗糙，未区分不同类型的异常（如连接异常、SQL执行异常），无法给客户端提供精准错误反馈，也不利于问题定位。
• 性能与资源管控问题：
  • 虽然SqlClient默认启用连接池，但手动创建连接并打开的方式若处理不当，可能导致连接泄漏，高并发场景下易出现数据库连接耗尽的问题。
  • 未对SQL执行时长、资源占用进行管控，客户端传入的复杂SQL（如关联多表的大查询）可能拖垮数据库性能，影响所有依赖该API的应用。
• 可维护性与扩展性极差：
  • 所有业务逻辑分散在各个客户端的SQL中，API本身无法统一维护或优化数据访问逻辑（比如要添加全局审计日志，需要修改所有客户端的SQL，几乎无法实现）。
  • 无法统一升级数据访问逻辑（如添加缓存层、读写分离策略），必须修改每个客户端的代码，扩展性为零。
• 契约缺失与客户端耦合：
  • API没有定义清晰的业务契约（如RESTful风格的资源端点、请求响应模型），客户端与API之间的耦合完全基于SQL语句，一旦数据库结构变更，所有涉及该结构的客户端SQL都需要修改，维护成本爆炸式增长。
  • 客户端无法借助API的契约进行代码生成、类型校验，只能手动拼接SQL和参数，容易出现语法错误、参数类型不匹配等问题。
• 事务支持不足：
  • 当前的Upsert方法仅支持单条SQL执行，客户端如果需要执行多步原子性操作（比如转账时同时修改两个账户的余额），无法通过API实现事务控制，只能在客户端自己处理，而客户端跨请求的事务几乎无法保证原子性。

内容的提问来源于stack exchange，提问作者Panko