Umbraco 12 Surface Controller POST接口无法访问，报400错误

一、先定位400错误的具体原因 #

400错误本质是请求不符合接口要求，先开启详细日志排查：
在appsettings.json中调整日志级别：

"Logging": {
  "LogLevel": {
    "Default": "Information",
    "Microsoft.AspNetCore": "Debug"
  }
}

启动项目后查看控制台或日志文件，会显示参数绑定失败、验证错误等具体信息，比如参数缺失、类型不匹配等。

二、改用模型绑定替代零散参数 #

零散参数容易出现绑定问题，改用强类型模型更易维护和排查：

1. 创建请求模型：

public class PlacementPostModel
{
    [Required(ErrorMessage = "TeamName为必填项")]
    public string TeamName { get; set; }
    
    [Required(ErrorMessage = "Iso3为必填项")]
    public string Iso3 { get; set; }
    
    public string FinalPlacement { get; set; }
    
    [Required(ErrorMessage = "TitleEvent为必填项")]
    public string TitleEvent { get; set; }
    
    public string EventYear { get; set; }
}

2. 修改Post接口：

[HttpPost]
[IgnoreAntiforgeryToken] // 外部系统调用需添加，避免CSRF验证拦截
public IActionResult PostPlacement([FromForm] PlacementPostModel model)
{
    // 先检查模型验证状态
    if (!ModelState.IsValid)
    {
        var errorMessages = ModelState.SelectMany(x => x.Value.Errors.Select(e => e.ErrorMessage));
        return BadRequest(string.Join("; ", errorMessages));
    }

    var rootContent = _contentQuery.ContentAtRoot().ToList();
    var placementItems = rootContent.FirstOrDefault(x => x.Name == "Data")!.Children.FirstOrDefault(x => x.Name == "Event Placements");

    // 后续业务逻辑代码

    return Ok();
}

三、解决CSRF验证拦截问题 #

Umbraco Surface Controller默认启用Anti-Forgery验证，外部系统调用时若无验证令牌会被拦截返回400：

• 给Post接口添加[IgnoreAntiforgeryToken]特性（仅用于可信外部系统调用，避免安全风险）。

四、确保请求格式正确 #

在Postman中配置请求时需注意：

• 请求方法选择POST
• 完整URL：https://localhost:44322/umbraco/surface/events/PostPlacement
• Body选择x-www-form-urlencoded或form-data，键名需与模型属性名大小写一致（如TeamName而非teamname）
• 不要设置Content-Type为application/json，[FromForm]仅接受表单格式请求。

五、不要手动添加路由 #

Surface Controller由Umbraco自动管理路由，自定义路由会导致冲突出现404，删除所有手动添加的路由配置，使用默认路由规则即可。

六、检查参数完整性与类型匹配 #

确保所有必填参数都已传入，参数类型与接口要求一致（比如EventYear定义为string，就不要传入无法转换为字符串的格式）。

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