如何创建适配7种类型的通用API端点？最佳实践咨询

我正尝试创建一个通用API端点，以适配以下7类数据类型：

FirstEnum?
SecondEnum?
DateTime? GenericDate1
DateTime? GenericDate2
String?
bool?
int? GenericInt1
int? GenericInt2
decimal?

这些类型对应数据库中的字段，部分类型存在两个数据库字段（如日期类型的GenericDate1、GenericDate2）。我尝试使用泛型T实现端点，但调用时返回404错误。后续还需要识别数据类型，以更新数据库中对应的正确字段。

我不知道是创建7个独立端点更好，还是采用通用端点方案。我了解过JObject的解决方案，但类型转换难度较大，想咨询此类场景下的最佳实践。

当前实现代码 #

API端点代码 #

public async Task<IActionResult> UpdateData<T>(long id, [FromBody] T value) 
{
    var result = await _dataService.UpdateData(id, value);
    if (!result)
        return NotFound();
    return Ok(result);
}

数据库更新逻辑示例 #

private async Task UpdateData(T newValue)
{
    switch (newValue)
    {
        case FirstEnum first:
            existingDataPoint.FirstEnum = first;
            break;
        case SecondEnum secondEnum :
            existingDataPoint.SecondEnum = secondEnum ;
            break;
        case bool genericBool:
            existingDataPoint.GenericBool = genericBool;
            break;
        case DateTime genericDate when newValue.Name == "GenericDate1":
            existingDataPoint.GenericDate1 = genericDate;
            break;
        case DateTime genericDate when newValue.Name == "GenericDate2":
            existingDataPoint.GenericDate2 = genericDate;
            break;
    }
}

问题分析与最佳实践建议 #

泛型端点返回404的原因 #

ASP.NET Core的路由系统无法自动推断泛型方法的类型参数T，所以无法匹配到对应的路由，这是导致404错误的核心原因。泛型方法并不适合直接作为API端点暴露。

两种方案对比与选择 #

1. 独立端点方案

• 优势：路由清晰（例如/api/UpdateFirstEnum/{id}、/api/UpdateGenericDate1/{id}），参数类型强校验，Swagger文档可自动生成，代码逻辑直观，调试和维护成本低，客户端调用无需额外传递类型标识。
• 劣势：存在少量重复代码，但可以通过将数据库更新的公共逻辑提取到服务层来复用，例如统一处理数据查询、保存变更等操作。

2. 优化后的通用端点方案

放弃泛型，改用带类型标识的DTO来传递数据，避免路由匹配问题：

public class UpdateRequestDto
{
    public string FieldKey { get; set; } // 例如"FirstEnum"、"GenericDate1"
    public object Value { get; set; }
}

对应的端点和更新逻辑调整为：

// API端点
public async Task<IActionResult> UpdateData(long id, [FromBody] UpdateRequestDto request) 
{
    if (!ValidateRequest(request)) // 新增参数校验逻辑
        return BadRequest("无效的请求参数");
    
    var result = await _dataService.UpdateData(id, request);
    if (!result)
        return NotFound();
    return Ok(result);
}

// 数据库更新逻辑
private async Task<bool> UpdateData(long id, UpdateRequestDto request)
{
    var existingDataPoint = await _dbContext.DataPoints.FindAsync(id);
    if (existingDataPoint == null)
        return false;

    switch (request.FieldKey)
    {
        case "FirstEnum":
            if (Enum.TryParse(request.Value.ToString(), out FirstEnum enumValue))
                existingDataPoint.FirstEnum = enumValue;
            break;
        case "GenericDate1":
            if (DateTime.TryParse(request.Value.ToString(), out DateTime dateValue))
                existingDataPoint.GenericDate1 = dateValue;
            break;
        case "GenericInt2":
            if (int.TryParse(request.Value.ToString(), out int intValue))
                existingDataPoint.GenericInt2 = intValue;
            break;
        // 其他字段类型的处理逻辑
    }

    await _dbContext.SaveChangesAsync();
    return true;
}

• 优势：仅需维护一个端点，便于统一处理权限校验、日志记录等横切关注点。
• 劣势：需要手动处理类型转换和参数校验，容易出现类型转换错误；Swagger文档需额外配置才能清晰展示请求结构；客户端调用需明确传递字段标识，增加了调用复杂度。

方案选择建议 #

• 如果字段类型数量较少（当前为7类），优先选择独立端点方案，它的开发效率、可维护性和API易用性都更优。
• 若业务需求要求必须使用单一通用端点，那么采用带类型标识的DTO方案是更稳妥的选择，避免使用JObject方案（类型转换繁琐、缺乏强类型校验，调试难度大）。

额外优化点 #

• 对于枚举类型，建议在DTO中使用字符串或整数传递，避免直接传递枚举名称的拼写错误。
• 所有类型转换都要加异常处理或TryParse逻辑，避免因客户端传入非法值导致接口报错。

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