ASP.NET MVC 5标准API端点实现及返回规范咨询

一、错误场景的HTTP状态码与响应格式选择 #

针对第三方调用的标准API，必须遵循REST语义化规范，不同错误场景应返回对应HTTP状态码+结构化JSON响应：

• 用户名/密码验证失败：返回401 Unauthorized，同时返回JSON说明错误原因（如{"Status":"failed","Message":"用户名或密码错误"}）。401状态码本身明确表示认证失败，第三方客户端可直接通过状态码识别，无需额外解析业务字段。
• 电话号码为空/部门为空：返回400 Bad Request，附带JSON错误信息（如{"Status":"failed","Message":"用户电话号码不能为空"}）。这类属于业务参数/数据不合法，400状态码符合语义，同时提供具体错误信息帮助第三方排查问题。
• 成功场景：返回200 OK，携带用户部门和电话信息的JSON（如{"Status":"success","Telephone":"138xxxxxxx","Department":"技术部"}）。

不建议统一返回200：这种方式会丢失HTTP状态码的语义化价值，增加客户端的判断逻辑复杂度，不符合标准API设计规范。

二、异常处理的响应规范 #

代码抛出异常时，应：

1. 记录详细异常日志（写入服务器日志系统，而非仅控制台输出），便于后续排查问题；
2. 返回500 Internal Server Error，同时返回友好的JSON错误信息，避免暴露内部异常细节（如数据库连接失败、LDAP服务不可用等敏感信息）。
   示例响应：{"Status":"failed","Message":"服务器内部错误，请稍后重试"}

三、优化后的Action方法代码 #

using System;
using System.DirectoryServices;
using System.DirectoryServices.AccountManagement;
using System.Web.Mvc;
using Newtonsoft.Json;

namespace LDAPMVCProject.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult UsersInfo(string username, string password)
        {
            var result = new DomainContext();

            try
            {
                string adServer = System.Web.Configuration.WebConfigurationManager.AppSettings["ADServerName"];
                string adAdminUser = System.Web.Configuration.WebConfigurationManager.AppSettings["ADUserName"];
                string adAdminPassword = System.Web.Configuration.WebConfigurationManager.AppSettings["ADPassword"];
                string adDomain = "mydomain.com";
                string adPath = $"LDAP://{adServer}:389/DC=mydomain,DC=com";

                // 1. 验证用户名密码
                using (var principalContext = new PrincipalContext(ContextType.Domain, adDomain, adAdminUser, adAdminPassword))
                {
                    if (!principalContext.ValidateCredentials(username, password))
                    {
                        var errorResponse = new { Status = "failed", Message = "用户名或密码错误" };
                        return new HttpUnauthorizedResult(JsonConvert.SerializeObject(errorResponse), "application/json");
                    }
                }

                // 2. 查询用户信息
                using (var directoryEntry = new DirectoryEntry(adPath, adAdminUser, adAdminPassword))
                using (var directorySearcher = new DirectorySearcher(directoryEntry))
                {
                    // 修复硬编码用户名，使用传入的参数
                    directorySearcher.Filter = $"(&(objectClass=user)(sAMAccountName={username}))";
                    // 指定要加载的属性，提升查询效率
                    directorySearcher.PropertiesToLoad.Add("telephoneNumber");
                    directorySearcher.PropertiesToLoad.Add("department");

                    SearchResult searchResult = directorySearcher.FindOne();
                    if (searchResult == null)
                    {
                        var errorResponse = new { Status = "failed", Message = "用户不存在" };
                        return new HttpStatusCodeResult(System.Net.HttpStatusCode.BadRequest, JsonConvert.SerializeObject(errorResponse));
                    }

                    // 提取电话号码
                    if (searchResult.Properties.Contains("telephoneNumber"))
                    {
                        result.Telephone = searchResult.Properties["telephoneNumber"][0].ToString();
                    }

                    // 提取部门
                    if (searchResult.Properties.Contains("department"))
                    {
                        result.Department = searchResult.Properties["department"][0].ToString();
                    }

                    // 3. 验证电话和部门是否为空
                    if (string.IsNullOrEmpty(result.Telephone))
                    {
                        var errorResponse = new { Status = "failed", Message = "用户电话号码不能为空" };
                        return new HttpStatusCodeResult(System.Net.HttpStatusCode.BadRequest, JsonConvert.SerializeObject(errorResponse));
                    }

                    if (string.IsNullOrEmpty(result.Department))
                    {
                        var errorResponse = new { Status = "failed", Message = "用户部门不能为空" };
                        return new HttpStatusCodeResult(System.Net.HttpStatusCode.BadRequest, JsonConvert.SerializeObject(errorResponse));
                    }

                    // 4. 返回成功响应
                    var successResponse = new { Status = "success", Telephone = result.Telephone, Department = result.Department };
                    return Content(JsonConvert.SerializeObject(successResponse), "application/json");
                }
            }
            catch (Exception ex)
            {
                // 记录异常日志（建议使用日志框架如NLog、Serilog）
                // Logger.Error(ex, "获取用户信息时发生异常");
                var errorResponse = new { Status = "failed", Message = "服务器内部错误，请稍后重试" };
                return new HttpStatusCodeResult(System.Net.HttpStatusCode.InternalServerError, JsonConvert.SerializeObject(errorResponse));
            }
        }
    }

    // 假设的DomainContext类
    public class DomainContext
    {
        public string Telephone { get; set; }
        public string Department { get; set; }
    }
}

代码优化说明 #

• 修复了原代码中硬编码用户名的问题，使用传入的username参数进行查询；
• 优化LDAP查询，仅加载需要的属性（telephoneNumber、department），提升性能；
• 统一了响应格式，所有场景都返回JSON结构，包含Status和Message（或业务数据）；
• 异常处理部分移除了控制台输出，改为返回标准500错误响应，同时保留日志记录逻辑；
• 使用HttpUnauthorizedResult、HttpStatusCodeResult明确返回对应HTTP状态码。

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