JsonApiDotNetCore

一个用于使用 ASP.NET Core 和 Entity Framework Core 构建符合 JSON:API 标准的 REST API 的框架。包含对 Atomic Operations 扩展的支持。

该库的最终目标是通过提供开箱即用的功能，尽可能消除样板代码，例如排序、过滤、分页、稀疏字段集选择以及侧载相关资源。您只需专注于定义资源并实现自定义业务逻辑。该库围绕依赖注入设计，使扩展性变得极其简单。

[!NOTE] OpenAPI 支持已停止。参见 https://github.com/json-api-dotnet/JsonApiDotNetCore/issues/2059。

入门

以下步骤描述了如何创建一个 JSON:API 项目。

创建一个新的 ASP.NET Core Web API 项目：

dotnet new webapi --no-openapi --use-controllers --name ExampleJsonApi
cd ExampleJsonApi

安装 JsonApiDotNetCore 包，以及您首选的 Entity Framework Core 提供程序：

dotnet add package JsonApiDotNetCore
dotnet add package Microsoft.EntityFrameworkCore.Sqlite

声明你的实体，并使用 JsonApiDotNetCore 特性进行标注：

[Resource]
public class Person : Identifiable<long>
{
    [Attr] public string? FirstName { get; set; }
    [Attr] public string LastName { get; set; } = null!;
    [HasMany] public ISet<Person> Children { get; set; } = new HashSet<Person>();
}

定义你的 DbContext，使用示例数据填充数据库：

public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<Person> People => Set<Person>();

    protected override void OnConfiguring(DbContextOptionsBuilder builder)
    {
        builder.UseSqlite("Data Source=SampleDb.db");
        builder.UseAsyncSeeding(async (dbContext, _, cancellationToken) =>
        {
            dbContext.Set<Person>().Add(new Person
            {
                FirstName = "John",
                LastName = "Doe",
                Children =
                {
                    new Person
                    {
                        FirstName = "Baby",
                        LastName = "Doe"
                    }
                }
            });
            await dbContext.SaveChangesAsync(cancellationToken);
        });
    }
}

在 Program.cs 中配置 Entity Framework Core 和 JsonApiDotNetCore：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>();
builder.Services.AddJsonApi<AppDbContext>(options =>
{
    options.UseRelativeLinks = true;
    options.IncludeTotalResourceCount = true;
});

var app = builder.Build();
app.UseRouting();
app.UseJsonApi();
app.MapControllers();
await CreateDatabaseAsync(app.Services);
app.Run();

static async Task CreateDatabaseAsync(IServiceProvider serviceProvider)
{
    await using var scope = serviceProvider.CreateAsyncScope();
    var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await dbContext.Database.EnsureDeletedAsync();
    await dbContext.Database.EnsureCreatedAsync();
}

启动您的 API
```
dotnet run
```

发送 GET 请求以获取数据：

GET http://localhost:5000/people?filter=equals(firstName,'John')&include=children HTTP/1.1

展开以查看 JSON 响应

{
  "links": {
    "self": "/people?filter=equals(firstName,%27John%27)&include=children",
    "first": "/people?filter=equals(firstName,%27John%27)&include=children",
    "last": "/people?filter=equals(firstName,%27John%27)&include=children"
  },
  "data": [
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "firstName": "John",
        "lastName": "Doe"
      },
      "relationships": {
        "children": {
          "links": {
            "self": "/people/1/relationships/children",
            "related": "/people/1/children"
          },
          "data": [
            {
              "type": "people",
              "id": "2"
            }
          ]
        }
      },
      "links": {
        "self": "/people/1"
      }
    }
  ],
  "included": [
    {
      "type": "people",
      "id": "2",
      "attributes": {
        "firstName": "Baby",
        "lastName": "Doe"
      },
      "relationships": {
        "children": {
          "links": {
            "self": "/people/2/relationships/children",
            "related": "/people/2/children"
          }
        }
      },
      "links": {
        "self": "/people/2"
      }
    }
  ],
  "meta": {
    "total": 1
  }
}

了解更多

以下链接解释了本项目提供的内容、其存在的原因，以及如何使用它。

关于

什么是 JSON:API，我为什么应该使用它？ (博客, 2017)
务实的 JSON:API 设计 (视频, 2017)
JSON:API 与 JsonApiDotNetCore (视频, 2021)
JsonApiDotNetCore 4.0 版本发布 (博客, 2020)
JSON:API、ASP.NET Core、EmberJS (视频, 2017)

官方文档

示例

examples 目录提供可直接运行的示例 API 项目，其文档见此处。
integration tests 目录涵盖了许多高级用例，其文档见此处。这包括批处理、多租户、授权、软删除、混淆 ID、资源继承、备用路由、自定义元数据、错误处理和日志记录等主题。
Ember.js Todo List App 展示了一个 JsonApiDotNetCore API 和一个使用令牌认证的 Ember.js 客户端。

兼容性

以下图表应有助于您根据环境选择最佳版本。另请参阅我们的版本策略。

.NET	Entity Framework Core	JsonApiDotNetCore	状态
10	10	5.10.0+	稳定
9	9	5.5.0+	稳定
8	8, 9	5.5.0+	稳定
7	7	5.0.3 - 5.6.0	已停止支持
6	7	5.0.3 - 5.6.0	已停止支持
6	6	5.0.0 - 5.6.0	已停止支持
5	5	4.x	已停止支持
Core 3.1	3.1, 5	4.x	已停止支持
Core 2.x	2.x	3.x	已停止支持

试用最新构建

每次提交到 master 分支后，都会自动发布一个新的预发布 NuGet 包到 feedz.io。要试用它，请按照以下步骤操作：

在与 .sln 文件相同的目录中创建一个 nuget.config 文件，内容如下：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="json-api-dotnet" value="https://f.feedz.io/json-api-dotnet/jsonapidotnetcore/nuget/index.json" />
    <add key="NuGet" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

在你的 IDE 中，浏览来自 json-api-dotnet 源的包列表。确保列表中包含预发布包

贡献

有问题、发现 bug 或想提交代码更改？请参阅我们的贡献指南。

从源码构建

要在本地构建此仓库的代码，请运行：

dotnet build

在本地运行测试需要访问 PostgreSQL 数据库。如果你已安装 docker，可以通过以下方式启动：

pwsh run-docker-postgres.ps1

然后运行测试：

dotnet test

或者，要构建、运行所有测试、生成代码覆盖率报告和 NuGet 包：

pwsh Build.ps1

赞助者

我们感谢以下赞助者，他们为团队提供了免费使用其工具的许可证。

你喜欢这个项目吗？考虑赞助，或者通过给我们的仓库点个星来支持我们。

JsonApiDotNetCore

入门

了解更多

关于

官方文档

示例

相关项目

兼容性

试用最新构建

贡献

从源码构建

赞助者