---
title: "SHOPLINE 应用结构"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/shopline-cli/app-structure'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/shopline-cli/app-structure.md'
---
# SHOPLINE 应用结构

[使用 SHOPLINE CLI 创建应用](https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/shopline-cli/build-apps-using-shopline-cli.md)会生成一套标准的应用目录结构，这一标准的应用框架可以帮助你更加高效和便捷地进行应用开发与配置。

## 目录结构
执行以下命令以进行项目初始化

```shell
npm create @shoplinedev/app
```

通过 [CLI 初始化应用](https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/shopline-cli/build-apps-using-shopline-cli.md?lang=zh-hans-cn) 后，会得到如下项目目录结构

```bash
- <App Name>
  |-- app	                     服务端开发的目录入口
      └──shopline.web.toml	     服务端开发配置文件
  |-- web
      |-- src
          └── index.tsx
      |-- vite.config.ts
      └── shopline.web.toml	     Web前端开发配置文件
  |-- package.json
  |-- shopline.app.toml     	 应用配置文件
```

以下为主要的项目文件说明

| 文件 | 描述 |
| --- | --- |
| shopline.app.toml | 应用相关的配置文件，具体可以看[shopline.app.toml介绍](#app) |
| shopline.web.toml | 应用开发的配置文件，具体可以看[shopline.web.toml介绍](#web) |
| package.json | 文件中主要包含了应用开发的相关依赖以及不同的开发命令。 |
| app/** | 应用的服务端目录文件 |
| web/** | 应用浏览器端目录文件 |


## 主要配置文件

### shopline.app.toml{#app}
通过 `shopline.app.toml` 文件，开发者可以在项目中配置应用相关的设置。开发者能够将这些设置嵌入到代码项目中，并通过 `CLI` 将项目配置更新至 `Partner Portal`。

```toml
appName = "shopline-app-template"
appKey = "b54f8adfeee2722203bb462a1045b773f3d51510d86"
appUrl = "https://volkswagen-quantitative-continuous-timing.trycloudflare.com"
appCallbackUrlList = [
  "https://volkswagen-quantitative-continuous-timing.trycloudflare.com/api/auth/callback"
]

[access_scopes]
scopes = "write_products"

```
| 属性 | 类型 | 是否必要 | 描述 |
| --- | --- | --- | --- |
| appName | `string` | 是 | 应用名称 |
| appKey | `string` | 是 | 唯一的标识符，用于区分和验证 APP；可通过开发者中心应用设置页面获取。 |
| appUrl | `string` | 是 | 可预览的应用地址 |
| appCallbackUrlList | `string[]` | 是 |  应用回调地址列表 用于授权完成后可以跳到的回调处理地址 |
| scopes | `string` | 是 | 应用需要申请的权限点，如果是多个权限点，需要用逗号的形式隔开 |

### shopline.web.toml{#web}
你可以通过 shopline.web.toml 文件配置应用启动相关的设置。CLI 在启动时会读取目录下的所有 shopline.web.toml 文件，并执行其中 `commands` 配置下的脚本命令。<br/>
例如，你是一名 Node.js 开发者，并且你在 `commands.dev` 配置中设置了命令 `yarn run dev`。应用启动时，CLI 会通过 shell 执行 `yarn run dev` 来启动该进程，并在进程中添加 CLI 提供的进程变量。有关进程和进程变量相关内容请参考 [进程约定](#process)。

下表说明文件的具体配置信息：

| 属性 | 类型 | 是否必要 | 描述 |
| --- | --- | --- | --- |
| type | `backend`&#124; `frontend` | 是 | Server类型 |
| commands.dev | `string` | 是 | 启动命令 |
| commands.build | `string` | 否 | 构建命令 |

在提供的应用模板中，我们为你内置了两个 `shopline.web.toml` 配置文件，分别代表了 `Node 服务端`和`React 浏览器端`的配置。`CLI`将会扫描这两个文件，并同时启动两个进程，为它们分配 BACKEND_PORT 和 FRONTEND_PORT，前端会通过 Vite 的代理功能将流量转发到后端进程。

## 进程约定{#process}
启动应用时，CLI 会获取存储在 Partner Portal 中的应用配置信息，并将部分应用信息其作为环境变量传递给启动进程。

SHOPLINE CLI 通过识别 `shopline.web.toml`配置文件中的 `type`字段来确定进程类型是 `backend` 还是 `frontend`，并据此构建服务。

### 前端进程
为了配置和前端进程，请确保在配置`shopline.web.toml`文件时，按照规范设定 type 字段为 frontend，CLI 在启动服务时会读取对应的 type 配置，CLI 会将前端端口号作为内网穿透的地址，生成对应的环境变量启动前端进程。 前端进程中的 web.toml 文件配置建议配置到 `<App Name>/web/` 文件夹下。

##### 环境变量

- SHOPLINE_APP_KEY：应用对应的 appKey，可通过`Partner Portal`应用设置页面获取。
- SHOPLINE_APP_SECRET：应用对应的 appSecret，可通过`Partner Portal`应用设置页面获取。
- SCOPES：应用申请的权限点内容。
- SHOPLINE_APP_URL：应用的预览地址。
- BACKEND_PORT：后端服务的端口号。

### 服务端进程
在同时具有应用开发服务端进程和前端进程的情况下，关于服务端进程部分的介绍可以采用以下规范化表达：<br/>
服务端的启动需要另外一个`shopline.web.toml`的配置文件。在该配置文件中，需要指定 type 字段的数值为`backend`。服务端进程中的 web.toml 文件配置建议配置到 `<App Name>/app/` 文件夹下

##### 环境变量

- SHOPLINE_APP_KEY：应用对应的 appKey，可通过`Partner Portal`应用设置页面获取。
- SHOPLINE_APP_SECRET：应用对应的 appSecret，可通过`Partner Portal`应用设置页面获取。
- SCOPES：应用申请的权限点内容。
- SHOPLINE_APP_URL： 应用的预览地址。
- FRONTEND_PORT： 前端服务的端口号。