快速上手

这一篇只做一件事：让你在本地把后端跑起来，能调通 API。包含了环境切换和生产部署的注意事项。

源码仓库：gitcode.com/soulsoft/blog

你需要准备什么

工具	最低版本	检查方式
仓颉 SDK	1.1.0+	cjc --version
MariaDB / MySQL	8.0+	mysql --version
sqlsharp_utils	—	代码生成工具，需要克隆编译

第1步：初始化数据库

项目根目录有 blog.sql，里面包含全部建表语句和初始数据。

mysql -u root -p < blog.sql

执行完会创建 blog 库，包含 8 张表（user、blog_post、category、tag、post_tag、comment、star、follow）和 6 个视图（v_blog_post、v_comment、v_latest_post、v_popular_post、v_top_starred_post、v_user_profile），还有示例文章和用户数据。

数据库连接配置在 web-api/appsettings.Development.json：

{
  "ConnectionStrings": {
    "default": "mariadb://localhost:3306?username=root&password=你的密码&database=blog&pool.max.size=100&pool.max.idle.size=100"
  }
}

如果你的 MariaDB 端口或密码不同，改这个文件里的连接字符串就行。

第2步：下载并编译代码生成工具

这个项目用 sqlsharp_utils 做 DB-First 代码生成（从数据库生成实体类）。

git clone https://gitcode.com/soulsoft/sqlsharp_utils.git
cd sqlsharp_utils
cjpm update
cjpm build

编译完成后，把 dbgen 可执行文件复制到 web-api/ 目录下（项目里已经有一个 dbgen.exe，你也可以直接用）。

第3步：生成实体代码

数据库表结构确定后，运行代码生成脚本：

cd web-api
./entity.bat

这一步会生成三个目录下的文件：

目录	内容	说明
src/domain/entities/	BlogPost.cj、User.cj、Comment.cj...	表映射实体
src/domain/views/	VBlogPost.cj、VComment.cj...	视图实体
src/domain/models/	BlogPostModel.cj、UserModel.cj...	DTO 序列化模型

以后数据库结构变了，重跑这个脚本就行，不要手改生成的文件。

第4步：启动后端

cd web-api

# 安装依赖
cjpm update

# 编译
cjpm build

# 运行
cjpm run

默认端口是 5000。启动后你可以验证：

• API 服务：http://localhost:5000
• 健康检查：http://localhost:5000/health
• Swagger 文档：http://localhost:5000/openapi

第5步：调几个接口试试

后端启动后，用 curl 或 Postman 调接口验证功能：

# 登录
curl -X POST http://localhost:5000/api/Connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=123456"

# 返回 { "accessToken": "...", "expiresIn": 3600 }

# 拿文章列表
curl -X POST http://localhost:5000/api/Blog/getBlogPostList \
  -H "Content-Type: application/json" \
  -d '{"pageIndex": 1, "pageSize": 10}'

# 文章详情
curl -X POST "http://localhost:5000/api/Blog/getBlogPostDetail?id=1"

# 获取分类
curl -X POST http://localhost:5000/api/Blog/getCategories

项目中预置了三个用户，密码都是 123456：

用户名	说明
admin	管理员，有多篇文章
root	普通用户
alice	普通用户

环境切换

项目支持多环境配置：

# 方式一：环境变量
export CANGJIE_ENVIRONMENT=Development   # 或 Production

# 方式二：命令行参数
cjpm run -- --environment Development

配置文件按环境分：

web-api/
├── appsettings.json                 # 公共配置
├── appsettings.Development.json     # 开发环境（本地数据库）
└── appsettings.Production.json      # 生产环境（线上数据库）

健康检查

后端提供了 /health 端点：

curl http://localhost:5000/health
# 返回 "Healthy"

可以配置到容器编排工具（Docker、K8s）做存活检查。

跑不通怎么办

按顺序排查：

1. 数据库连不上 — 确认 MariaDB 在运行，appsettings.Development.json 里的密码正确
2. 编译报错 — 确认 cjpm update 跑过，依赖拉全了
3. entity.bat 报错 — 确认 dbgen 在 web-api/ 目录下，且有执行权限
4. 接口 500 — 看控制台日志，大概率是数据库视图没建、连接字符串不对或 sqlsharp_utils 版本不匹配

推荐的生产改进

当前项目能直接跑，但上线前有几件事建议做：

改进项	当前状态	建议
密码加密	明文存储	改用 bcrypt 或 argon2
JWT 密钥	硬编码字符串	改用 RSA 密钥对或从配置读取
HTTPS	未启用	前面加 Nginx/Caddy 做 TLS 终止
日志	控制台输出	接入文件日志或日志收集系统
数据库迁移	直接执行 SQL	引入迁移工具

容器化部署参考

# web-api/Dockerfile
FROM cangjie:1.1.0
COPY . /app
WORKDIR /app
RUN cjpm build
CMD ["cjpm", "run", "--", "--environment", "Production"]
EXPOSE 5000