# 文档概览 Source: https://docs.sisk-framework.org/zh-cn/docs/index.html ## 欢迎 - [入门](https://docs.sisk-framework.org/zh-cn/docs/getting-started.md): 欢迎阅读 Sisk 文档！ Sisk 是一个开源的轻量级 .NET HTTP 框架。您可以使用它构建独立的 Web 服务，将 HTTP 模块嵌入现有应用程序，或在反向代理后运行服务，仅使用所需的配置。 Sisk 的价值观包括代码透明性、模块化、性能和可扩展性。它能够处理不同的应用模式，包括 RESTful … - [安装](https://docs.sisk-framework.org/zh-cn/docs/installing.md): 您可以通过 Nuget、dotnet cli 或 其他选项 安装 Sisk。您可以通过在开发者控制台中运行以下命令轻松设置 Sisk 环境： Shell dotnet add package Sisk.HttpServer 此命令将在您的项目中安装 Sisk 的最新版本。 - [本机 AOT 支持](https://docs.sisk-framework.org/zh-cn/docs/native-aot.md): .NET Native AOT 允许发布本机 .NET 应用程序，这些应用程序是自给自足的，不需要在目标主机上安装 .NET 运行时。此外，Native AOT 提供诸如： 应用程序大小大大减小 初始化速度大大提高 内存消耗降低 Sisk Framework 本质上允许几乎所有功能使用 Native AOT，而无需对源 … - [部署 Sisk 应用程序](https://docs.sisk-framework.org/zh-cn/docs/deploying.md): 部署 Sisk 应用程序的过程包括将项目发布到生产环境中。虽然这个过程相对简单，但有一些细节需要注意，以避免对部署的基础设施造成安全和稳定性的损害。 理想情况下，在进行了所有可能的测试后，您应该准备好将应用程序部署到云端。 发布应用程序 # 发布 Sisk 应用程序或服务是生成生产就绪和优化的二进制文件。在这个例子中， … - [使用 SSL](https://docs.sisk-framework.org/zh-cn/docs/ssl.md): 在需要安全性的环境中进行开发时，使用 SSL 可能是必要的，例如大多数 Web 开发场景。Sisk 基于 HttpListener 工作，而 HttpListener 不支持原生 HTTPS，只支持 HTTP。不过，有一些变通方法可以让你在 Sisk 中使用 SSL。见下文： 通过 … - [Cadente](https://docs.sisk-framework.org/zh-cn/docs/cadente.md): Cadente 是 Sisk 的一个实验性的托管 HTTP/1.1 监听器实现。它作为默认的 System.Net.HttpListener 的替代品，提供了更大的控制和灵活性，尤其是在非 Windows 平台上。 概述 # 默认情况下，Sisk 使用 HttpListener (来自 System.Net) 作为其底 … - [在 Windows 上配置命名空间保留](https://docs.sisk-framework.org/zh-cn/docs/registering-namespace.md): 注意 此配置是可选的，仅在您希望 Sisk 在 Windows 上使用 HttpListener 引擎监听除 “localhost” 之外的主机时才需要。 Sisk 使用 HttpListener 网络接口，该接口将虚拟主机绑定到系统以监听请求。 在 Windows 上，此绑定有些限制，只允许将 localhost 绑 … - [Changelogs](https://docs.sisk-framework.org/zh-cn/docs/changelogs.md): 每对 Sisk 进行的更改都会通过更改日志记录。你可以在 这里 查看所有 Sisk 版本的更改日志。 - [常见问题](https://docs.sisk-framework.org/zh-cn/docs/faq.md): 关于 Sisk 的常见问题。 Sisk 是开源的吗？ # 完全开源。Sisk 使用的所有源代码都已发布并经常在 GitHub 上更新。 是否接受贡献？ # 只要贡献符合 Sisk 哲学，所有贡献都非常欢迎！贡献不仅限于代码！您可以通过文档、测试、翻译、捐款和帖子等方式贡献。 Sisk 是否有资金支持？ # 不。目前没有 … ## 基础 - [路由](https://docs.sisk-framework.org/zh-cn/docs/fundamentals/routing.md): The Router 是构建服务器的第一步。它负责保存 Route 对象，这些对象是将 URL 及其方法映射到服务器执行的操作的端点。每个操作负责接收请求并向客户端返回响应。 路由是路径表达式（“路径模式”）与它们可以监听的 HTTP 方法的配对。当向服务器发出请求时，服务器会尝试找到匹配该请求的路由，然后调用该路由的 … - [请求处理](https://docs.sisk-framework.org/zh-cn/docs/fundamentals/request-handlers.md): 请求处理程序，也称为“中间件”，是在路由器上执行请求之前或之后运行的函数。它们可以在每个路由或每个路由器上定义。 请求处理程序有两种类型： BeforeResponse：定义请求处理程序将在调用路由器操作之前执行。 AfterResponse：定义请求处理程序将在调用路由器操作之后执行。在此上下文中发送 HTTP 响应 … - [请求](https://docs.sisk-framework.org/zh-cn/docs/fundamentals/requests.md): 请求是表示 HTTP 请求消息的结构体。HttpRequest 对象包含了在整个应用程序中处理 HTTP 消息的实用函数。 一个 HTTP 请求由方法、路径、版本、头部和正文组成。 在本文档中，我们将教您如何获取这些元素。 获取请求方法 # 要获取收到的请求的方法，可以使用 Method 属性： C# static … - [响应](https://docs.sisk-framework.org/zh-cn/docs/fundamentals/responses.md): 响应表示对 HTTP 请求的 HTTP 响应对象。它们由服务器发送给客户端，以指示对资源、页面、文档、文件或其他对象的请求。 HTTP 响应由状态、头部和内容组成。 在本文档中，我们将教您如何使用 Sisk 构建 HTTP 响应。 设置 HTTP 状态 # 自 HTTP/1.0 起，HTTP 状态列表保持不变，Sisk … ## 功能 - [日志](https://docs.sisk-framework.org/zh-cn/docs/features/logging.md): 您可以配置 Sisk 自动写入访问日志和错误日志。可以定义日志轮转、扩展名和频率。 LogStream 类提供了一种异步写入日志并将其保存在可等待写入队列中的方式。LogStream 类实现了 IAsyncDisposable，确保在流关闭之前写入所有未完成的日志。 本文将向您展示如何为应用程序配置日志记录。 基于文件 … - [Server Sent Events](https://docs.sisk-framework.org/zh-cn/docs/features/server-sent-events.md): Sisk 开箱即支持通过 Server Sent Events 发送消息。您可以创建一次性和持久的连接，在运行时获取这些连接并使用它们。 此功能受到浏览器的某些限制，例如只能发送文本消息且无法永久关闭连接。服务器端关闭的连接会导致客户端每隔 5 秒（某些浏览器为 3 秒）尝试重新连接。 这些连接对于在服务器向客户端发送 … - [Web 套接字](https://docs.sisk-framework.org/zh-cn/docs/features/websockets.md): Sisk 也支持 Web 套接字，例如接收和发送消息给客户端。 此功能在大多数浏览器中运行良好，但在 Sisk 中仍属实验性。若您发现任何错误，请在 GitHub 上报告。 接收消息 # WebSocket 消息按顺序接收，排队等待 ReceiveMessageAsync 处理。超时、操作被取消或客户端断开时，此方法不 … - [Discard 语法](https://docs.sisk-framework.org/zh-cn/docs/features/discard-syntax.md): HTTP 服务器可以用于监听来自操作的回调请求，例如 OAuth 身份验证，并在接收到该请求后丢弃。这在需要后台操作但不想为其设置整个 HTTP 应用程序的情况下很有用。 以下示例展示了如何使用 CreateListener 创建一个在端口 5555 上监听的 HTTP 服务器并等待下一个上下文： C# using … - [依赖注入](https://docs.sisk-framework.org/zh-cn/docs/features/instancing.md): 通常，会为请求的生命周期专门分配成员和实例，例如数据库连接、已验证的用户或会话令牌。实现这一点的一种可能方式是通过 HttpContext.RequestBag ，它创建一个在整个请求生命周期中都存在的字典。 该字典可以被 请求处理程序 访问，并在整个请求中定义变量。例如，一个验证用户的请求处理程序将用户设置在 … - [流式内容](https://docs.sisk-framework.org/zh-cn/docs/features/content-streaming.md): Sisk 支持读取和发送流式内容到和从客户端。这一功能对于在请求的生命周期中序列化和反序列化内容的内存开销非常有用。 请求内容流 # 小内容会自动加载到 HTTP 连接缓冲区内存中，快速加载到 HttpRequest.Body 和 HttpRequest.RawBody。对于较大的内容，可以使用 … - [启用 CORS（跨源资源共享）在 Sisk](https://docs.sisk-framework.org/zh-cn/docs/features/cors.md): Sisk 有一个工具，可以用于处理 跨源资源共享 (CORS) 当公开服务时。这一功能不是 HTTP 协议的一部分，而是由 W3C 定义的 Web 浏览器的特定功能。这种安全机制可以防止 Web 页面向不同于提供 Web 页面的域发送请求。服务提供者可以允许某些域访问其资源，或者只允许一个域。 同源 # 要识别为“同源 … - [文件服务器](https://docs.sisk-framework.org/zh-cn/docs/features/file-server.md): Sisk 提供 Sisk.Http.FileSystem 命名空间，其中包含用于提供静态文件、目录列表和文件转换的工具。此功能允许您从本地目录提供文件，支持范围请求（音频/视频流）和自定义文件处理。 提供静态文件 # 提供静态文件的最简方式是使用 Router.MapFileSystem。此方法将 URL 前缀映射到磁 … ## 扩展 - [模型上下文协议](https://docs.sisk-framework.org/zh-cn/docs/extensions/mcp.md): 可以使用 Sisk.ModelContextProtocol 包构建为使用大型语言模型（LLM）的代理模型提供上下文的应用程序： Bash dotnet add package Sisk.ModelContextProtocol 该包公开了用于构建在 Streamable HTTP 上运行的 MCP 服务器的实用类和方 … - [JSON-RPC 扩展](https://docs.sisk-framework.org/zh-cn/docs/extensions/json-rpc.md): Sisk 提供了一个实验性的 JSON-RPC 2.0 API 模块，帮助你创建更简洁的应用程序。此扩展严格实现 JSON-RPC 2.0 传输接口，并提供通过 HTTP GET、POST 请求以及 Sisk 的 WebSocket 进行传输。 你可以使用下面的命令通过 Nuget 安装此扩展。请注意，在实验/测试版中 … - [SSL 代理](https://docs.sisk-framework.org/zh-cn/docs/extensions/ssl-proxy.md): 警告 此功能是实验性的，不应在生产环境中使用。如果您想让 Sisk 与 SSL 协作，请参阅 此文档。 Sisk SSL 代理是一个模块，提供了 Sisk 中 ListeningHost 的 HTTPS 连接，并将 HTTPS 消息路由到不安全的 HTTP 上下文。该模块是为使用 HttpListener 运行的服务提 … - [基本身份验证](https://docs.sisk-framework.org/zh-cn/docs/extensions/basic-auth.md): Basic Auth 包添加了一个请求处理程序，能够处理基本身份验证方案，并且只需进行很少的配置和努力，即可在 Sisk 应用程序中使用。 基本 HTTP 身份验证是一种最小的输入形式，通过用户 ID 和密码对请求进行身份验证，会话由客户端完全控制，并且没有身份验证或访问令牌。 有关基本身份验证方案的更多信息，请参阅 … - [服务提供者](https://docs.sisk-framework.org/zh-cn/docs/extensions/service-providers.md): 服务提供者是一种将 Sisk 应用程序移植到不同环境的方式，使用可移植的配置文件。该功能允许您在不修改应用程序代码的情况下更改服务器端口、参数和其他选项。该模块依赖于 Sisk 构造语法，可以通过 UsePortableConfiguration 方法进行配置。 一个配置提供者是通过 … - [INI 配置提供程序](https://docs.sisk-framework.org/zh-cn/docs/extensions/ini-configuration.md): Sisk 有一种除了 JSON 之外的获取启动配置的方法。实际上，任何实现 IConfigurationReader 的管道都可以与 PortableConfigurationBuilder.WithConfigurationPipeline一起使用，读取服务器配置从任何文件类型。 … - [API 文档](https://docs.sisk-framework.org/zh-cn/docs/extensions/api-documentation.md): Sisk.Documenting 扩展允许您自动为 Sisk 应用程序生成 API 文档。它利用您的代码结构和特性来创建一个完整的文档站点，支持导出为 Open API（Swagger）格式。 警告 此软件包目前仍在开发中，尚未发布。其行为和 API 可能会在未来的更新中发生更改。 由于此软件包尚未在 NuGet 上提 … ## 高级 - [手动（高级）设置](https://docs.sisk-framework.org/zh-cn/docs/advanced/manual-setup.md): 当您需要自行组装服务器组件时使用手动设置，例如一个进程必须暴露多个主机、端口、路由器或自定义服务器配置。对于大多数应用程序，构建器 API 更简洁，应该优先使用。手动设置在您想直接控制四个核心部件时非常有用：Router、一个或多个 ListeningHost 对象、HttpServerConfiguration，以及 … - [请求生命周期](https://docs.sisk-framework.org/zh-cn/docs/advanced/request-lifecycle.md): 下面通过一个 HTTP 请求的示例解释请求的完整生命周期。 接收请求： 每个请求在请求本身和将要发送给客户端的响应之间创建一个 HTTP 上下文。该上下文来自 Sisk 内置的监听器，可以是 HttpListener、Kestrel 或 Cadente。 外部请求验证：对请求进行 … - [转发解析器](https://docs.sisk-framework.org/zh-cn/docs/advanced/forwarding-resolvers.md): Forwarding Resolver 是一个帮助解码通过请求、代理、CDN 或负载均衡器识别客户端信息的工具。当您的 Sisk 服务通过反向或正向代理运行时，客户端的 IP 地址、主机和协议可能与原始请求不同，因为这是从一个服务转发到另一个服务。此 Sisk 功能允许您在处理请求之前控制并解析这些信息。这些代理通常会 … - [Http server handlers](https://docs.sisk-framework.org/zh-cn/docs/advanced/http-server-handlers.md): 在 Sisk 0.16 版本中，我们引入了 HttpServerHandler 类，旨在扩展 Sisk 的整体行为并为 Sisk 提供额外的事件处理程序，例如处理 Http 请求、路由、上下文袋等。 该类集中处理整个 HTTP 服务器以及单个请求生命周期中发生的事件。Http 协议没有会话概念，因此无法在请求之间保留信 … - [每个服务器的多个监听主机](https://docs.sisk-framework.org/zh-cn/docs/advanced/multi-host-setup.md): Sisk Framework 一直支持在每个服务器上使用多个主机，也就是说，一个 HTTP 服务器可以监听多个端口，每个端口都有自己的路由器和在其上运行的服务。 这样，就可以轻松地在单个 HTTP 服务器上使用 Sisk 分离职责并管理服务。下面的示例展示了创建两个 ListeningHost，每个监听不同的端口，使用 … - [HTTP 服务器引擎](https://docs.sisk-framework.org/zh-cn/docs/advanced/server-engines.md): Sisk Framework 被分成几个包，其中主包（Sisk.HttpServer）不包含一个基本的 HTTP 服务器 - 默认情况下，HttpListener 被用作 Sisk 的主要引擎来执行服务器的低级别角色。 HTTP 引擎实现了 Sisk 提供的应用层以下的层次。这个层次负责连接管理、消息的序列化和反序列化 …