Postcard

一个面向编程初学者的 HTTP 服务器示例项目。代码简单、易读，帮助你理解"客户端 / 服务器"是怎么一回事。

本项目使用 C# + ASP.NET Core（.NET 8） 编写，只暴露两个简单的 API。

---

一、这个项目在做什么？

一句话：它启动了一个服务器，在电脑上监听某个网址（URL），等待客户端发来请求，然后返回结果。

服务器（Server）和客户端（Client）的关系，可以想象成"餐厅"：

• 服务器 = 餐厅厨房：一直开着门，等着接单。
• 客户端 = 顾客：可以是浏览器、curl 命令，或手机 App。
• 请求（Request） = 顾客点的菜。
• 响应（Response） = 厨房做好后端上来的菜。

一次完整的交互流程

客户端                          服务器
  │                               │
  │  1. 发送请求                    │
  │  GET http://localhost:5000/    │
  │ ─────────────────────────────▶│
  │                               │  2. 服务器收到请求
  │                               │     根据网址（路由）决定怎么处理
  │                               │  3. 生成响应内容
  │  4. 返回响应                    │
  │  "Postcard server is running" │
  │ ◀─────────────────────────────│
  │                               │
  │  5. 客户端拿到结果，显示出来        │

在本项目里：

1. 你运行 dotnet run，服务器就"开门营业"，监听 http://localhost:5000。
2. 客户端访问这个网址，就是"点单"。
3. 服务器根据网址（我们叫它路由 / route）判断：
   • 访问 / → 返回一句纯文本问候。
   • 访问 /api/hello → 返回一段 JSON 数据。
4. 客户端收到返回内容并显示。

---

二、API 说明

方法（Method）	路径（Path）	说明
GET	/	返回一句纯文本：Postcard server is running。
GET	/api/hello	返回 JSON 问候。可带查询参数 name，不带时默认为 world。

GET 是最常见的请求方法，表示"我想获取一些数据"。 **查询参数（query parameter）**就是网址 ? 后面的 key=value，例如 ?name=Jak。

---

三、准备环境：安装 .NET 运行时

本项目基于 .NET 8。运行前需要先安装 .NET SDK（SDK 包含了运行和编译所需的一切）。

1. 下载安装

前往官方页面下载并安装 .NET 8 SDK： 👉 https://dotnet.microsoft.com/download/dotnet/8.0

• Windows / macOS：下载安装包，双击一路"下一步"即可。
• Linux：按页面上的指令用包管理器安装。

2. 验证是否安装成功

打开终端（Windows 用 PowerShell 或 CMD，macOS / Linux 用 Terminal），输入：

dotnet --version

如果输出类似 8.0.204 这样的版本号，就说明安装成功了。

无需额外配置环境变量：.NET 安装程序会自动把 dotnet 命令加入系统路径。

---

四、运行项目

在项目根目录（含有 Postcard.csproj 的这一层）打开终端，执行：

dotnet run

首次运行会自动下载依赖并编译，稍等片刻。看到类似下面的输出就代表启动成功：

Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

服务器已经在 http://localhost:5000 上"开门营业"了。保持这个终端窗口开着，服务器才会一直运行。按 Ctrl + C 可以停止。

---

五、动手试一试

另开一个终端窗口，用 curl 命令（大多数系统自带）向服务器发请求：

# 1. 访问根路径，拿到纯文本
curl http://localhost:5000/
# 输出：Postcard server is running

# 2. 带上 name 参数，拿到 JSON
curl "http://localhost:5000/api/hello?name=Jak"
# 输出：{"message":"Hello, Jak!"}

# 3. 不带参数，使用默认值 world
curl http://localhost:5000/api/hello
# 输出：{"message":"Hello, world!"}

你也可以直接在浏览器里打开 http://localhost:5000/api/hello?name=Jak，效果一样。

---

六、代码在哪里？

• Program.cs — 程序主入口。这里创建服务器、定义两个 API，并启动监听。
• Postcard.csproj — 项目配置文件，声明使用 .NET 8 和 Web 项目类型。
• appsettings.json — 应用配置（例如日志级别）。

打开 Program.cs，你会发现整个服务器不到 15 行代码。核心就是三步：

var builder = WebApplication.CreateBuilder(args); // 1. 创建应用
var app = builder.Build();

app.MapGet("/", () => "Postcard server is running"); // 2. 定义路由：谁访问 / 就返回这句话

app.Run(); // 3. 启动，开始监听请求

---

七、小提示

• 这两个 API 没有做身份验证（authentication），因为它们只返回公开、无敏感信息的内容，作为示例足够了。真实项目中如果要暴露敏感数据，请先加上鉴权。
• GET /api/hello 返回的是 JSON 格式——这是前后端之间最常用的数据交换格式。