# MicroApi

**Repository Path**: victortzeng/MicroApi

## Basic Information

- **Project Name**: MicroApi
- **Description**: No description available
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2021-06-23
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[English](https://github.com/x-trip/MicroApi/blob/master/README-EN.md)

# MicroApi

基于 [SqlKata Query Builder](https://github.com/sqlkata/querybuilder) 的表驱动 Restful API 中间件。

> **v1.2.1**：目标框架 **net8 / net9 / net10**。支持资源映射；未声明资源默认不可访问；PUT/DELETE 必须带过滤条件。

## 支持的数据库

1. MySql *[MicroApi.MySql](https://www.nuget.org/packages/MicroApi.MySql/)*
2. SqlServer *[MicroApi.SqlServer](https://www.nuget.org/packages/MicroApi.SqlServer/)*
3. PostgreSQL *[MicroApi.PostgreSQL](https://www.nuget.org/packages/MicroApi.PostgreSQL/)*
4. Oracle *[MicroApi.Oracle](https://www.nuget.org/packages/MicroApi.Oracle/)*
5. Sqlite *[MicroApi.Sqlite](https://www.nuget.org/packages/MicroApi.Sqlite/)*
6. Firebird *[MicroApi.Firebird](https://www.nuget.org/packages/MicroApi.Firebird/)*

## 接口认证中间件

*[MicroApi.Authorization](https://www.nuget.org/packages/MicroApi.Authorization)*

可选 claim：`microapi.permission`，格式 `resource:METHOD` / `resource:*` / `*:*`（resource 为 API 资源名，不是物理表名）。

## 示例

[MicroApi.Demo](https://github.com/x-trip/MicroApi/tree/master/MicroApi.Demo)

## 用法

简写（路径名 = 表名）：

```csharp
services.AddMicroApi(option =>
    {
        option.AuthorizeType = AuthorizeType.JWT;
        option.ApiRoutePrefix = "api";
        option.AllowTable("Users", ApiHttpMethods.All);
    })
    .UseSqlServer(connectionString)
    .AddMicroApiAuthorization();
```

资源映射（推荐：路径/JSON 与库表解耦）：

```csharp
services.AddMicroApi(option =>
    {
        option.MapResource("users", r =>
        {
            r.Table("app_user");
            r.Methods(ApiHttpMethods.Get | ApiHttpMethods.Put | ApiHttpMethods.Delete);
            r.Key("id", "user_id");
            r.Column("name", "user_name");
            r.Column("email", "user_email");
        });
    })
    .UseSqlServer(connectionString);
```

```text
GET /api/users          → SELECT user_id, user_name, user_email FROM app_user
GET /api/users/12       → WHERE user_id = 12（未找到 404）
PUT /api/users/12       → 路径 id 即过滤条件
```

一旦使用 `Column(...)`，仅映射列可读写；未映射列（如 `password_hash`）不会出现在查询与响应中。只声明 `Key`、不声明 `Column` 时，其它列仍按 API 名 = 数据库列名处理。

本地原型若需临时放开全部表（仍校验标识符与写保护；`/{id}` 默认按列 `id`）：

```csharp
option.AllowAllTables = true;
```

分页保护：`MaxPageSize`（默认 200）、`DefaultPageSize`（默认 10）。

中间件顺序：

```csharp
app.UseAuthentication();
app.UseAuthorization();
app.UseMicroApi();
```

## API 格式

路径：`/{ApiRoutePrefix}/{resource}` 或 `/{ApiRoutePrefix}/{resource}/{id}`

`/{id}` 需要 `MapResource(...).Key(...)`。未配置主键时访问带 id 的路径返回 400。POST 不允许路径 id。

### GET

- 分页：`?page=&size=` 或 `?offset=&limit=`（带 `/{id}` 时忽略分页）
- 排序：`?orderAsc=col1,col2` / `?orderDesc=col1`（使用 API 列名）
- 条件：`?col=value`、`col.ge` / `gt` / `le` / `lt` / `in` / `like`

### POST

新增，JSON body 使用 API 列名。

### PUT / DELETE

按查询条件和/或路径 `{id}` 更新/删除；**至少需要一个过滤条件**，否则返回 400。

## 变动日志

### 1.2.1

- **移除 net6.0 / net7.0**（均已 EOL，且 SqlKata 4 仅支持 net8+）
- 升级 SqlKata / SqlKata.Execution 至 4.0.1
- SqlServer 驱动改为 `Microsoft.Data.SqlClient`
- 按 TFM 对齐 Npgsql、Microsoft.Data.Sqlite、JwtBearer；其余驱动与测试包升至当前稳定版

### 1.3.0

- 增加目标框架 `net9.0`、`net10.0`（同时保留 net6/net7/net8）

### 1.2.0

- 新增 `MapResource`：路由别名（`users` → `app_user`）、列映射、主键 `Key`
- 支持 `GET/PUT/DELETE /{prefix}/{resource}/{id}`；GET 单条不存在返回 404
- 列映射开启后，请求、过滤、排序、响应均使用 API 列名，隐藏未映射的数据库列
- `AllowTable` 仍可用，行为与 1.1 兼容（不含 `/{id}`，除非再 `MapResource` 并声明 `Key`）

### 1.1.0

- 默认资源白名单；PUT/DELETE 禁止无条件写删
- 表/列标识符校验；分页上限
- Scoped 数据库连接；异步 Handler
- JWT 与可选 `microapi.permission`；CI 改为 Trusted Publishing