API设计的注意事项

SignalR API 设计时的注意事项

通过Andrew Stanton-nurse

本文提供了用于构建基于 SignalR 的 Api 的指南。

使用自定义对象参数来确保向后兼容性

将参数添加到 SignalR 集线器方法 (在客户端或服务器) 是重大更改 这意味着较旧的客户端/服务器会在尝试调用不带适当数量的参数的方法时出现错误。 但是,将属性添加到自定义对象参数是一项重大更改。 这可以用于设计兼容的 Api 时可复原的客户端或服务器上的更改。

例如,考虑如下所示的服务器端 API:

public async Task<string> GetTotalLength(string param1)
{
    return param1.Length;
}

JavaScript 客户端调用此方法使用invoke,如下所示:

connection.invoke("GetTotalLength", "value1");

如果以后服务器方法中添加第二个参数,较旧的客户端不会提供此参数值。 例如:

public async Task<string> GetTotalLength(string param1, string param2)
{
    return param1.Length + param2.Length;
}

当旧客户端尝试调用此方法时,它会收到如下错误:

Microsoft.AspNetCore.SignalR.HubException: Failed to invoke 'GetTotalLength' due to an error on the server.

在服务器上,将看到一条日志消息如下:

System.IO.InvalidDataException: Invocation provides 1 argument(s) but target expects 2.

旧客户端仅发送一个参数,但较新版本的服务器 API 所需的两个参数。 使用自定义对象作为参数提供了更大的灵活性。 让我们重新设计要使用自定义对象的原始 API:

public class TotalLengthRequest
{
    public string Param1 { get; set; }
}

public async Task GetTotalLength(TotalLengthRequest req)
{
    return req.Param1.Length;
}

现在,客户端使用对象调用方法:

connection.invoke("GetTotalLength", { param1: "value1" });

无需添加参数,将属性添加到TotalLengthRequest对象:

public class TotalLengthRequest
{
    public string Param1 { get; set; }
    public string Param2 { get; set; }
}

public async Task GetTotalLength(TotalLengthRequest req)
{
    var length = req.Param1.Length;
    if (req.Param2 != null)
    {
        length += req.Param2.Length;
    }
    return length;
}

当旧客户端发送一个参数,额外Param2属性将保留null 你可以检测到通过检查由较旧的客户端发送的消息Param2null并应用默认值。 新的客户端可以发送两个参数。

connection.invoke("GetTotalLength", { param1: "value1", param2: "value2" });

相同的方法适用于在客户端上定义的方法。 可以从服务器端发送自定义对象:

public async Task Broadcast(string message)
{
    await Clients.All.SendAsync("ReceiveMessage", new
    {
        Message = message
    });
}

在客户端上,访问Message属性,而无需使用参数:

connection.on("ReceiveMessage", (req) => {
    appendMessageToChatWindow(req.message);
});

如果你稍后决定要将消息的发件人添加到负载,请向对象添加属性:

public async Task Broadcast(string message)
{
    await Clients.All.SendAsync("ReceiveMessage", new
    {
        Sender = Context.User.Identity.Name,
        Message = message
    });
}

较旧的客户端不应为Sender值,因此将其忽略。 新的客户端可以通过接受更新,以读取新属性:

connection.on("ReceiveMessage", (req) => {
    let message = req.message;
    if (req.sender) {
        message = req.sender + ": " + message;
    }
    appendMessageToChatWindow(message);
});

在这种情况下,新的客户端也是不提供的旧服务器的容错Sender值。 由于旧的服务器不会提供Sender值时,客户端检查以查看是否存在之前对其进行访问。