# my-app-server-core

**Repository Path**: taotaojs/my-app-server-core

## Basic Information

- **Project Name**: my-app-server-core
- **Description**: ts基础项目，用于快速开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# server-core

`server-core` is a reusable server template extracted from the existing `server` project.

For direct dependency integration from other projects, see `DIRECT-INTEGRATION.zh-CN.md`.
For splitting into a standalone repo and publishing as a private npm package, see `PUBLISH-AS-PRIVATE-NPM.zh-CN.md`.

It includes:

- Express bootstrap and common middlewares
- env loading and validation
- Pino logging
- MySQL and Redis connection helpers
- OAuth2 login and token validation
- auth middleware and typed `req.auth`
- image upload support
- unified success/error response helpers
- an extension point for business routes

There are two integration modes:

- use the built-in `/api/auth` and `/api/uploads` routes directly
- disable built-in routes and mount your own business implementation, while still reusing core config and middleware

## Directory Layout

```text
server-core
├─ src
│  ├─ app.ts
│  ├─ server.ts
│  ├─ config
│  ├─ middleware
│  ├─ modules
│  ├─ services
│  ├─ types
│  └─ utils
└─ tests
```

## Start Locally

```bash
cd server-core
copy .env.example .env
conda run -n dev npm run dev
```

Default built-in routes:

- `GET /health`
- `POST /api/auth/login`
- `GET /api/auth/me`
- `POST /api/uploads/images`

## Add Your Own APIs

Create your own business routes and mount them with `registerRoutes`.

```ts
import { Router } from "express";
import { authMiddleware, createCoreApp } from "./src";

const orderRouter = Router();

orderRouter.get("/", authMiddleware, (_req, res) => {
  res.json({ code: 0, success: true, message: "ok", data: [] });
});

const app = createCoreApp({
  registerRoutes(appInstance) {
    appInstance.use("/api/orders", orderRouter);
  },
});
```

This keeps business code outside the shared core so later upgrades stay simple.

## Override Built-In Modules

If your project needs a custom `/api/auth/me` response or a different upload policy, disable the built-in routes and mount your own routers.

```ts
import { createCoreApp } from "./src";
import { authRouter } from "./src/modules/auth/auth.routes";

const app = createCoreApp({
  enableAuthRoutes: false,
  enableUploadRoutes: false,
  registerRoutes(appInstance) {
    appInstance.use("/api/auth", authRouter);
    appInstance.use("/api/orders", orderRouter);
  },
});
```

This is exactly the pattern recommended for business projects that need shared infrastructure but different domain behavior.

## Recommended Update Strategy

To make template updates easy across many projects, use a two-layer model:

1. Keep shared infrastructure inside `server-core`.
2. Keep each project's business routes, controllers, services, and migrations outside `server-core`.
3. Make business projects depend on `server-core` by version instead of copying core files into business code.

### Preferred: package version upgrade

Best when you can publish private packages.

1. Put `server-core` in its own git repo.
2. Publish it to your private npm registry.
3. Let every business project depend on `server-core` with semver.
4. Upgrade all projects with a version bump such as `npm update server-core`.

Benefits:

- fastest multi-project rollout
- easy rollback by version
- changelog can describe breaking changes clearly

### Alternative: git subtree

If you do not have a private package registry, keep `server-core` in a dedicated repo and use `git subtree`.

Initial import:

```bash
git subtree add --prefix server-core <server-core-repo> main --squash
```

Pull later updates:

```bash
git subtree pull --prefix server-core <server-core-repo> main --squash
```

Or in this repository:

```powershell
./ps/sync-server-core.ps1 -Repo <server-core-repo> -Ref main -Mode pull
```

This keeps the shared core in one place while allowing each project to keep its own business APIs.

## Upgrade Boundary

Safe to update together:

- `src/config`
- `src/middleware`
- `src/services/oauth2.service.ts`
- `src/utils`
- built-in auth and upload modules

Should remain in business projects:

- domain routes
- domain controllers/services
- project-specific DB tables and migrations
- project-specific `me` profile expansion logic

## Suggested Consumer Structure

```text
your-project
├─ server-core
├─ src
│  ├─ app.ts
│  ├─ index.ts
│  └─ modules
```

In this setup, `server-core` changes can be upgraded without rewriting business APIs.