踏步而歌 發表於 2024-12-13 13:04:00

Chats 开发指南

<h1 id="chats-开发指南">Chats 开发指南</h1>
<p>欢迎使用 Chats！在我上一篇博客 https://www.cnblogs.com/sdcb/p/18597030/sdcb-chats-intro 中，我介绍了 Chats 的各种功能，但所有功能都是用代码一行一行写出来的。</p>
<p>在这个指南中，我将帮助您快速上手开发，了解如何在开发阶段使用和配置 Chats 项目。Chats 在开发阶段采用前后端分离的模式，但在生产环境中前后端会合并为一个发布包。</p>
<h2 id="技术基础">技术基础</h2>
<ul>
<li><strong>后端：</strong> 使用 C#/ASP.NET Core 开发。</li>
<li><strong>前端：</strong> 使用 Next.js/React/TypeScript 开发。</li>
<li><strong>CSS：</strong> 使用 Tailwind CSS。</li>
</ul>
<h2 id="环境需求">环境需求</h2>
<ul>
<li>Git</li>
<li>.NET SDK 8.0</li>
<li>Node.js &gt;= 20</li>
<li>Visual Studio Code</li>
<li>Visual Studio 2022（可选但推荐）</li>
</ul>
<h2 id="获取代码">获取代码</h2>
<p>首先，克隆 Chats 的代码仓库：</p>
<pre><code class="language-bash">git clone https://github.com/sdcb/chats.git
</code></pre>
<h2 id="前后端共同开发">前后端共同开发</h2>
<h3 id="后端开发指南">后端开发指南</h3>
<ol>
<li>
<p>使用 Visual Studio 打开解决方案：</p>
<p>在根目录下找到 <code>chats/Chats.sln</code> 解决方案文件并打开。在 Visual Studio 中，您将看到一个名为 <code>Chats.BE</code> 的网站项目。</p>
</li>
<li>
<p>运行项目：</p>
<ul>
<li>按 F5 运行项目。默认配置会检查 SQLite 数据库文件 <code>chats.db</code> 是否存在，如果不存在，会自动创建在 <code>./AppData</code> 目录并初始化数据库。</li>
<li>服务将在 <code>http://localhost:5146</code> 上运行，并提供 API 服务。如果在开发模式下运行 (<code>ASPNETCORE_ENVIRONMENT=Development</code>)，Swagger UI 将在 <code>http://localhost:5146/swagger</code> 上可用。</li>
</ul>
</li>
<li>
<p>配置文件说明：</p>
<p>默认配置在 <code>appsettings.json</code> 中，但强烈建议使用 <code>userSecrets.json</code> 管理敏感信息。这可以避免在代码库中泄露敏感的开发配置。</p>
<p><strong>默认配置结构如下：</strong></p>
<pre><code class="language-json">{
"Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
},
"AllowedHosts": "*",
"FE_URL": "http://localhost:3001",
"ENCRYPTION_PASSWORD": "this is used for encrypt auto increment int id, please set as a random string.",
"DBType": "sqlite",
"ConnectionStrings": {
    "ChatsDB": "Data Source=./AppData/chats.db"
}
}
</code></pre>
<p><strong>配置选项解释：</strong></p>
<ul>
<li><code>Logging</code>: 管理日志级别，默认记录信息级别的日志。</li>
<li><code>AllowedHosts</code>: 配置允许访问的主机名，<code>*</code> 表示接受所有。</li>
<li><code>FE_URL</code>: 前端的URL，默认指向 <code>http://localhost:3001</code>。前端可以通过 CORS 跨域访问后端。默认3000端口无需额外配置。</li>
<li><code>DBType</code>: 数据库类型，支持 <code>sqlite</code>（默认）、<code>mssql</code> 和 <code>postgresql</code>。</li>
<li><code>ConnectionStrings:ChatsDB</code>: 数据库 <code>ADO.NET</code> 连接字符串，随 <code>DBType</code> 而变。</li>
<li><code>ENCRYPTION_PASSWORD</code>: 用于加密自增 ID。生产环境中应设置为随机字符串，避免直接暴露 ID。</li>
</ul>
<p><strong>为什么使用整数+加密而非 GUID？</strong></p>
<p>在 Chats 项目初期，我们确实是使用的GUID，但是由于下列2个原因并经过慎重考虑，我换成了自增整数Id：</p>
<ul>
<li>GUID 字段较大，占用更多空间；</li>
<li>GUID 作为聚集索引会导致索引碎片，影响性能；</li>
</ul>
<p><strong>管理敏感配置：</strong></p>
<p>不建议在 <code>appsettings.json</code> 中直接修改配置项。可以通过 Visual Studio 使用 <code>userSecrets.json</code>：</p>
<ul>
<li>
<p>Visual Studio: 右键点击 <code>Chats.BE</code> 项目 -&gt; <code>管理用户机密</code>。</p>
</li>
<li>
<p>CLI: 使用以下命令管理用户机密。</p>
<pre><code class="language-bash">dotnet user-secrets init
dotnet user-secrets set "key" "value"
dotnet user-secrets list
</code></pre>
</li>
</ul>
<p>这可以避免在提交代码时不小心将敏感信息上传。</p>
</li>
<li>
<p>不使用 Visual Studio 的运行方式：</p>
<p>进入后端目录：</p>
<pre><code class="language-bash">cd ./chats/src/BE
dotnet run
</code></pre>
</li>
</ol>
<h3 id="前端开发指南">前端开发指南</h3>
<ol>
<li>
<p>进入前端目录：</p>
<pre><code class="language-bash">cd ./chats/src/FE
</code></pre>
</li>
<li>
<p>创建 <code>.env.local</code> 文件并指定后端 URL：</p>
<pre><code class="language-bash">echo "API_URL=http://localhost:5146" &gt; .env.local
</code></pre>
</li>
<li>
<p>安装依赖并运行开发服务器：</p>
<pre><code class="language-bash">npm i
npm run dev
</code></pre>
</li>
</ol>
<p>运行后，前端服务将监听 <code>http://localhost:3000</code>。后端已有 CORS 配置支持无需额外配置。</p>
<h2 id="仅前端开发">仅前端开发</h2>
<p>对于专注于前端开发的场景，我们提供了一个已经部署好的后端开发环境：</p>
<ol>
<li>
<p>克隆仓库：</p>
<pre><code class="language-bash">git clone https://github.com/sdcb/chats.git
</code></pre>
</li>
<li>
<p>进入前端目录并指定远程后端：</p>
<pre><code class="language-bash">cd ./chats/src/FE
echo "API_URL=https://chats-dev.starworks.cc:88" &gt; .env.local
</code></pre>
<p>这个环境已经默认允许了 http://localhost:3000 这个地址的跨域访问行为。</p>
</li>
<li>
<p>安装依赖并运行：</p>
<pre><code class="language-bash">npm i
npm run dev
</code></pre>
</li>
</ol>
<h3 id="注意事项">注意事项</h3>
<p>如果想模拟生产打包过程，请执行：</p>
<pre><code class="language-bash">npm run build
</code></pre>
<p>此命令会在当前目录生成 <code>./out</code> 文件夹，其中包含所有必要的静态文件。</p>
<h2 id="仅后端开发">仅后端开发</h2>
<p>对于专注于后端开发的场景，可以使用打包好的前端文件：</p>
<ol>
<li>
<p>克隆仓库并进入后端目录：</p>
<pre><code class="language-bash">git clone https://github.com/sdcb/chats.git
cd ./chats/src/BE
</code></pre>
</li>
<li>
<p>下载并解压前端静态文件放置到 <code>wwwroot</code>：</p>
<p><strong>Linux 下执行：</strong></p>
<pre><code class="language-bash">curl -O https://github.com/sdcb/chats/releases/latest/download/chats-fe.zip
unzip chats-fe.zip
cp -r chats-fe/* wwwroot/
</code></pre>
<p><strong>Windows 下执行：</strong></p>
<pre><code class="language-powershell">Invoke-WebRequest -Uri "https://github.com/sdcb/chats/releases/latest/download/chats-fe.zip" -OutFile "chats-fe.zip"
Expand-Archive -Path "chats-fe.zip" -DestinationPath "."
Copy-Item -Path ".\chats-fe\*" -Destination ".\wwwroot" -Recurse -Force
</code></pre>
<h3 id="注意">注意</h3>
<ol>
<li>
<p>我同时还将上述的 https://github.com/sdcb/chats/releases/latest/download/chats-fe.zip 地址上传到了我个人的 Minio 文件服务器，地址为：https://io.starworks.cc:88/chats/latest/chats-fe.7z</p>
<p>如果您直接从 Github 上下载速度太慢，可以换成这个地址。</p>
</li>
<li>
<p>这个地址对应的 <code>chats-fe.zip</code> 附件是由 Github Actions 在代码合入 <code>main</code> 分支时自动生成来而，合入 <code>dev</code> 分支时并不会触发更新这个文件。</p>
</li>
</ol>
</li>
<li>
<p>运行后端：</p>
<pre><code class="language-bash">dotnet run
</code></pre>
<p>或者在 Visual Studio 中打开 <code>Chats.sln</code> 并运行 <code>Chats.BE</code> 项目。</p>
</li>
</ol>
<p>运行后，访问 <code>http://localhost:5146/login</code> 可以直接进入 Chats 的登录界面，实现前后端不分离的部署模式。</p>
<p>希望此指南可以帮助您顺利开展 Chats 项目的开发工作。如有任何问题，请查看源码中的文档或在 https://github.com/sdcb/chats 中创建issue来获得支持。</p><br><br>
来源：https://www.cnblogs.com/sdcb/p/18604712/chats-development-instruction
頁: [1]
查看完整版本: Chats 开发指南