Vol.Pro开发文档

接口返回字段大小写（JsonNormal）

核心结论

框架在 Program.cs 全局配置了 Newtonsoft 小驼峰（CamelCasePropertyNamesContractResolver），return Json(...) 会把 OrderNo 序列化为 orderNo。
生成表标准接口（getPageData 等）在 ApiBaseController 内已使用 JsonNormal，返回字段与 实体类 / 数据库定义一致（PascalCase）。
Partial 自定义接口 若返回给 vol-table、vol-form、弹框选数等，字段名须与前端 columns.field、editFormFields 完全一致，MUST 使用 return JsonNormal(...)，不要用 return Json(...)。

为什么需要 JsonNormal

返回方式	序列化规则	示例
`return Json(data)`	全局小驼峰	`Order_Id` → `order_Id` 或 `orderId`
`return JsonNormal(data)`	原属性名（`ContractResolver = null`）	`Order_Id` → `Order_Id`

JsonNormal 定义在 VolPro.Core.Controllers.Basic.VolController（所有 Partial Controller 的基类链上可用）：

protected JsonResult JsonNormal(object data, JsonSerializerSettings serializerSettings = null, bool formateDate = true)
{
    serializerSettings = serializerSettings ?? new JsonSerializerSettings();
    serializerSettings.ContractResolver = null;  // 取消小驼峰，保持原大小写
    // ...
    return Json(data, serializerSettings);
}

什么时候必须用 JsonNormal

场景	是否用 JsonNormal
Partial 自定义查询列表 `{ total, rows }` 供 vol-table	是
弹框选数、selectTable 自定义数据源	是
返回实体 `List<TEntity>` 给前端按字段名取值	是
树形表格 `{ rows }`、下拉 `{ key, value }` 与 columns 对齐	是
仅返回 `{ status, message }` 操作结果（前端不读业务字段）	建议仍用 JsonNormal（与框架 Success/Error 一致）
生成器标准 `getPageData` / `Add` / `Update`	已在 `ApiBaseController` 内 JsonNormal，无需改

自定义 API 写法（Partial Controller）

列表（与 getPageData 结构一致）：

[HttpPost, Route("getGoods")]
public IActionResult GetGoods([FromBody] PageDataOptions loadData)
{
    var gridData = _goodsService.GetPageData(loadData);
    return JsonNormal(gridData);  // rows 内字段保持 Order_Id、Qty 等原大小写
}

明细行：

[HttpGet, Route("getDetailRows")]
public async Task<IActionResult> GetDetailRows(Guid Order_Id)
{
    var rows = await _repository.FindAsIQueryable(x => x.Order_Id == Order_Id).ToListAsync();
    return JsonNormal(rows);
}

分页自定义查询：

[HttpPost, Route("searchItems")]
public async Task<IActionResult> SearchItems([FromBody] PageDataOptions options)
{
    var query = _repository.FindAsIQueryable(x => x.Enable == 1);
    var rows = await query.TakePage(options.Page, options.Rows).ToListAsync();
    return JsonNormal(new { total = await query.CountAsync(), rows });
}

Service 返回 WebResponseContent 时：

[HttpPost("DoAction")]
public async Task<IActionResult> DoAction([FromBody] Dictionary<string, object> data)
{
    var res = await _service.DoAction(data);
    // 业务数据在 res.Data 中，仍用 JsonNormal 保持字段大小写
    return JsonNormal(new { status = res.Status, message = res.Message, data = res.Data });
}

也可使用基类辅助方法（内部已是 JsonNormal）：

return Success("操作成功", data);
return Error("失败原因");

常见错误

现象	原因	处理
前端 `row.Order_Id` 为 undefined，只有 `row.order_Id`	用了 `return Json(...)`	改为 `JsonNormal`
vol-table 列不显示、选数回填失败	前后端 field 大小写不一致	Controller 用 JsonNormal + 核对 columns.field
与标准 getPageData 混用同一表	标准接口已是原大小写，自定义接口用了 Json	自定义接口统一 JsonNormal

前端注意