Skip to content
ydonghaoPublic

About

yarch —— 一种规范,多种方言:跨栈工程架构平台(25 份契约规约 + Java/Python/Web/Go 四栈平台构件与一行命令脚手架,机检防漂移)

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

yarch

Yuan's Architecture —— 一种规范,多种方言。 · English

License java-stack python-stack web-stack golang-stack Contract

跨项目复用的工程架构平台——不是又一个 CRUD 框架,而是让多个技术栈说同一种接口语言的契约体系。

为什么

痛点 yarch 的答案
每个 API 长得不一样 统一信封 RestResponse + 错误码段位表,任何栈报出同一个 code 语义唯一
排障跨栈拉不齐 ndjson 日志 + traceId 贯穿(W3C traceparent),Java/Go/Python/TS 一条链拉通
规约靠自觉、CR 靠人肉 契约断言测试 + ArchUnit / depcruise 机检——违反即测试失败
脚手架 fork 改码后升级困难 平台构件发版式升级,业务工程只改一行 version
AI 生成代码结构漂移 模板管结构、契约管行为,AI 施工不越界

从 0 到 1:一条命令生成工程

四个栈同一套契约,全部生成即合规——统一信封 · 14 码错误码 · traceId 贯穿 · 分页(页码 D6 + keyset 游标)· 幂等 · 逻辑删除 · 机检预置,业务代码只写业务。

Java · Maven archetype(零 clone,Central 已发版)

前置:JDK 21+、Docker。

# ① 生成 DDD 七包工程(换 -DarchetypeArtifactId=yarch-archetype-simple 即阿里五层档)
mvn archetype:generate -B \
  -DarchetypeGroupId=io.github.ydonghao \
  -DarchetypeArtifactId=yarch-archetype-ddd \
  -DarchetypeVersion=0.1.0 \
  -DgroupId=com.example -DartifactId=my-svc \
  -Dpackage=com.example.mysvc

# ② 起跑
cd my-svc
docker compose up -d      # PG17 + Redis7(生成工程自带)
mvn spring-boot:run       # Flyway 自动迁移 + 示例 CRUD → http://localhost:8080

可选验收:mvn verify 跑 ArchUnit 分层机检 + 契约断言 + Testcontainers 全链路。

Web · npm create(零 clone,npm 已发版)

前置:Node 22+、pnpm。

# ① 生成中后台工程(三档 UI 任选:Semi 默认 · 抖音系 / antd · 蚂蚁系 / arco · 字节系)
npm create @yarch/admin@latest ysaas-console               # Semi 档(默认)
npm create @yarch/admin@latest ysaas-console -- --ui antd  # 换 antd(arco 同理)

# ② 起跑
cd ysaas-console && pnpm install && pnpm dev   # → http://localhost:5173

比裸脚手架多给:契约底座预接线(信封解包 / traceId / 401 跳登录)· 工程名强制 registry 标准 · 底座 npm 版本化升级 · feature-first 分层机检。完整说明书:stacks/web/packages/create/README.md

Golang · yarch-init 生成器(clone 本仓一次;发版后零 clone)

前置:Go 1.24+;PG/Redis 可达(共享实例,或本机 Docker)。

# ① 生成 Hertz DDD 工程(服务名过 registry 校验:小写短横线、禁裸通用词)
git clone https://github.com/ydonghao/yarch.git
cd yarch/stacks/golang
go run ./cmd/yarch-init -module github.com/you/order-svc -out ~/code/order-svc

# ② 起跑
cd ~/code/order-svc
cp .env.example .env && vi .env   # 填 PG/Redis 地址(主路径连共享实例:独立 database 自动建库+迁移,无需本地 compose)
docker compose up -d              # 没有共享实例时:本机起 PG17 + Redis7,.env 主机改 localhost
go mod tidy && go run .           # → http://localhost:8080

生成工程 go.mod 的 replace 行指向你 clone 的本仓(联调期平台构件走本地源码);正式发版后删除该行、版本改正式 tag。

Python · yarch-init 生成器(clone 本仓一次;发版后零 clone)

前置:uv、Python 3.12+;PG/Redis 可达(共享实例,或本机 Docker)。

# ① 生成 FastAPI DDD 工程(服务名过 registry 校验:小写短横线、禁裸通用词)
git clone https://github.com/ydonghao/yarch.git
cd yarch/stacks/python
uv sync --all-packages && uv run yarch-init --service order-svc --out ~/code/order-svc

# ② 起跑
cd ~/code/order-svc
cp .env.example .env && vi .env   # 填 PG/Redis 地址(web 启动自动建库 + Alembic 自动迁移)
uv sync && uv run uvicorn main:app --reload   # → http://localhost:8000/docs(users 示例 /api/v1/users)
uv run celery -A celery_app worker -Q order-svc.default   # ③ 需要异步任务时另进程 worker/beat

发版后(tag stacks/python/vX.Y.Z → PyPI trusted publishing)零 clone 一条命令:uvx yarch-init@latest --service order-svc --out order-svc。

升级:平台发版式,业务工程只改版本号
# Java:改 pom 继承的 yarch-parent 版本一行(BOM 仲裁全链版本)
# Web:pnpm update @yarch/contract @yarch/react
# Golang:go get github.com/ydonghao/yarch/stacks/golang@vX.Y.Z(v0.1.0 已收录)
# Python:uv add "yarch-python@X.Y.Z"
契约速览
{ "code": 0, "message": "成功", "data": { }, "traceId": "0af7651916cd43dd8448eb211c80319c" }
  • code:0 成功 · 1xxx 通用 · 2xxx 认证 · 3xxx+ 业务注册
  • 日志:ndjson 一行一条(ts/level/service/env/traceId/logger/msg)
  • 分页:页码通道(D6 越界返回空页)+ 游标通道(keyset)
  • 幂等:Idempotency-Key 头 + Redis SET NX PX
国内访问加速(换源,三栈三行)

镜像均为官方源的代理缓存(发布只发官方源,镜像自动同步;刚发版的版本可能延迟几分钟):

# npm(web 栈)
npm config set registry https://registry.npmmirror.com

# Maven(java 栈)——写入 ~/.m2/settings.xml 的 <mirrors>
# <mirror><id>aliyun</id><mirrorOf>central</mirrorOf>
#   <url>https://maven.aliyun.com/repository/public</url></mirror>

# Go(golang 栈)
go env -w GOPROXY=https://goproxy.cn,direct

仓库结构

yarch/
├── contract/          # 契约层(唯一权威来源,29 份 v1.0 定稿)
│   ├── api/           #   四件套:信封 · 错误码 · 日志/traceId · REST 约定
│   ├── infra/         #   20 份:PG · MySQL · Redis · Kafka · MQ · 向量 · OLAP · 网关 · …
│   ├── web/           #   微前端规约(micro-app 默认档)
│   ├── clients/       #   客户端规约三份:client-shared · android · ios
│   └── registry.md    #   服务名(租户边界)唯一登记处
│
├── stacks/            # 栈实现层(发各自生态的包)
│   ├── java/          #   ✅ 16 模块:parent/BOM + 8 starter + 双 archetype + 双 examples
│   ├── python/        #   ✅ uv workspace 双发行版:yarch-python 构件 + yarch-init 生成器(DDD 模板)
│   ├── web/           #   ✅ 5 包:contract + react/vue 适配 + create-admin 生成器(三档单应用 + 基座/子应用微前端档)
│   ├── golang/        #   ✅ 3 module:契约内核 + 六构件 + DDD 模板
│   └── rust/          #   预留(触发式)
│
├── clients/           # android · ios 规约已定稿(实现触发式);miniprogram · desktop(Tauri) 按需生长
├── tools/             # locate-scaffolds → 将来 yarch init CLI
└── docs/              # 架构文档 + 对标解析(ruoyi/yudao/coli 缺口 G/E 决策清单)

已交付

Java(stacks/java/)

构件 能力
yarch-parent + yarch-bom 构建基线 + 版本唯一仲裁(Boot 4.1 / JDK 25 编 21 / Spotless 4 空格)
yarch-common 信封 / 14 码错误码表 / PageData / BusinessException / Asserts / Masks / TraceIds
yarch-web-… 异常矩阵 / 分页 / 幂等 / @RateLimited(1006) / @OperationLog / @SignedApi
yarch-logging-… ndjson 行协议 / TraceIdFilter(traceparent 优先)
yarch-persistence-… PG + MyBatis-Plus:逻辑删除 / 审计填充 / 分页下推 / keyset 游标
yarch-redis-… RedisKeys(首段=服务名)/ JSON+jsr310 / 分布式锁 / 跨实例幂等
yarch-http-… 出口传播:traceparent 注入 / 超时强制 / 信封解包 / 1008-1009
yarch-captcha-… 图形验证码 + Redis 一次性 token
yarch-auth-… JWT + 2xxx 矩阵 + @RequireRoles
yarch-test-… 契约断言 / ArchUnit 双规则集 / PG·Redis 容器基座
yarch-archetype-ddd DDD 七包(api/app/domain/crossdomain/infra/types/common)
yarch-archetype-simple 阿里五层(controller/service/manager/dao/model)
yarch-examples-×2 商品+订单双档活案例:幂等下单 / 锁竞争 / cache-aside / keyset / 状态机

Web(stacks/web/)

包 能力
@yarch/contract 信封类型/解包 / 错误码常量表 / ApiError / traceId / fetch 封装 / 导航端口
@yarch/react / @yarch/vue 框架薄适配(注入各 router 导航)
@yarch/create-admin 工程生成器:交互问答 + archetype 全量渲染 + registry 命名校验(golang yarch-init 对偶);--micro base|sub 生成微前端基座/子应用;全模板内置 AGENTS.md AI 施工守则
create/templates/admin-semi 默认档资产(Vite + React + Semi Design,抖音系)
create/templates/admin-antd antd 档资产(蚂蚁系)
create/templates/admin-arco Arco Design 档资产(字节系)
create/templates/base-semi / sub-semi 微前端档资产:基座(manifest 装配/共享运行时/登录态唯一)+ 子应用(独立·集成双模式,集成产物框架体积归零)
examples/admin-demo 全链路对接 Java 后端(验证码/分页/幂等/状态机)
examples/ysaas-console + ysaas-billing 微前端活案例:基座+子应用(事件上行/双模式/加载失败重试),playwright e2e 六用例

Python(stacks/python/)

构件 能力
yarch-python(PyPI) 契约内核三件(response/errcode/xerror)+ logx ndjson + trace/recovery/accesslog/幂等/限流中间件 + persist(逻辑删除/审计/分页 D6/Alembic)+ redix(key 规约/锁/幂等三态/固定窗口限流)+ httpx(traceparent 注入/1008·1009)+ celeryx(celery 规约强制默认)+ testx 契约断言
yarch-init(PyPI) 工程生成器:Jinja2 渲染 + registry 服务名校验 + 残留占位扫描;DDD 七包模板(users/celery 示例 + alembic + web/worker 双入口)

机检(违反即测试失败)

层 Java Web Python
契约断言 错误码 14 码逐码核对 + 信封形状 + ndjson 字段 错误码表逐码核对 + 解包语义 testx:14 码全表 + 信封/ndjson/PageData(跨栈 conformance 同表)
架构守卫 ArchUnit(DDD 依赖倒置 / 五层单向) depcruise(pages 薄入口 / 禁反向 / contract 零框架) import-linter(契约内核零框架 + 禁反向依赖)
代码风格 Spotless AOSP 4 空格(check 挂 verify) biome(规范单点) ruff check + format + mypy

契约与实现的关系

contract/(唯一权威,语言无关)
    ↓ 每栈一份方言实现
stacks/java    → RestResponse<T> · GlobalErrorCode · TraceIdFilter
stacks/web     → RestResponse<T> · errorCodes     · trace-id.ts
stacks/golang  → response.Response · errcode.Code  · middleware.Trace()
stacks/python  → response.Response · errcode.Code  · middleware.TraceMiddleware()
                   ↑
         实现与契约不一致 = bug(两侧均有防漂移断言)

状态

  • 契约层:29 份 v1.0 定稿(api 四件套 + infra 20 份 + web 微前端 + clients 三份 + registry)
  • Java:16 模块 reactor verify 全绿 · CI(JDK 21/25)
  • Web:contract 4/4 · depcruise 0 违规 · 生成后冒烟三档全绿(生成 → install → tsc → build)· 微前端集成 e2e 六用例全绿(playwright)· CI(Node 22/24)
  • Golang:3 module 全绿
  • Python:99 tests 全绿 · CI(Python 3.12/3.13,含生成工程冒烟)
  • 发版:Java 13 件 0.1.0 已上 Maven Central(2026-09-03,archetype:generate 零 clone 即用;源码锚 stacks/java/v0.1.0,后续版本推 tag stacks/java/vX.Y.Z 走 java-publish.yml);Web 三包 0.1.0 已上 npm(npm create @yarch/admin@latest 即用;源码锚 stacks/web/v0.1.0,后续推 tag 走 CI 发版);Golang stacks/golang/v0.1.0 已推 tag 并被 module proxy 收录(go get github.com/ydonghao/yarch/stacks/golang@v0.1.0 即用);Python PyPI trusted publishing 就绪(stacks/python/vX.Y.Z),tag 待推送——当前从本仓跑生成器(见上方从 0 到 1)

License

Apache-2.0

About

yarch —— 一种规范,多种方言:跨栈工程架构平台(25 份契约规约 + Java/Python/Web/Go 四栈平台构件与一行命令脚手架,机检防漂移)

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages