Create a new project

• Web Project

  • Web projects are for applications that require a web interface. Developing a web project is similar to building a Spring Boot-based web application with SOFA middleware.

  • Web projects work with the SOFAREST service to provide a frontend-backend separation solution based on the Java API for RESTful Web Services (JAX-RS) standard.

• Core project: Core projects are for backend services that do not have a user interface. Developing a core project is similar to building a Spring Boot-based non-web application (without servlet dependencies) with SOFA middleware.

This topic describes how to create a project and explains its structure.

Create a project

This section describes how to use the Maven tool to create SOFABoot Web and Core projects on your local machine. Before you start, complete the steps in Prerequisites.

Prerequisites

To run the code examples in this topic, you must first set up the SOFABoot runtime environment. For more information, see Set up the environment.

Procedure

1. Open the command line interface as a system administrator. Navigate to the folder where you want to create the project and run one of the following commands:

   • If you use the settings.xml file in the default Maven installation folder and have overwritten the original settings.xml file as described in Set up the environment, you can use the following Maven commands.

     • Web project:

       mvn archetype:generate -DarchetypeGroupId=com.alipay.sofa -DarchetypeArtifactId=sofaboot-web-archetype -DarchetypeVersion=1.0-SNAPSHOT -DarchetypeCatalog=internal

     • Core project:

       mvn archetype:generate -DarchetypeGroupId=com.alipay.sofa -DarchetypeArtifactId=sofaboot-core-archetype -DarchetypeVersion=1.0-SNAPSHOT -DarchetypeCatalog=internal

   • If you use the settings.xml file in a custom Maven installation folder and have overwritten the original settings.xml file as described in Set up the environment, you can use the following Maven commands.

     • Web project:

       mvn -s "custom_settings_path" archetype:generate -DarchetypeGroupId=com.alipay.sofa -DarchetypeArtifactId=sofaboot-web-archetype -DarchetypeVersion=1.0-SNAPSHOT -DarchetypeCatalog=internal

     • Core project:

       mvn -s "custom_settings_path" archetype:generate -DarchetypeGroupId=com.alipay.sofa -DarchetypeArtifactId=sofaboot-core-archetype -DarchetypeVersion=1.0-SNAPSHOT -DarchetypeCatalog=internal

       Important

       When you use a settings.xml file from a custom path, do not copy the Maven command directly. You must replace "custom_settings_path" with the actual file path. For example: "C:\apache-maven-3.3.3\conf\settingsXXX.xml".

2. During the process, you are prompted to enter the following information. You can configure them as needed:

   • groupId: The unique identifier for the project in the Maven repository. This is usually the reverse of your company or organization's domain name, such as com.yourCompanyName.sofa.

     Important

     You must create your groupId according to development standards to prevent issues during configuration scans.

   • artifactId: The project or application name, such as web-app or core-app.

   • version: The version number. The default is 1.0-SNAPSHOT. A SNAPSHOT is an unstable version of a project that is still in development. You can keep the default value.

   • package: The application package name. You can leave this field blank.

     Note

     The groupId, artifactId, and version elements form the basic coordinates of a Maven project.

3. After you complete the configuration, you are asked to confirm the information.

   • Enter Y to confirm and continue the installation.

   • Enter N to cancel and redefine the properties.

4. After you define the properties, the project creation process continues. When you see the following output, the project is created.

   [INFO]------------------------------------------------------------------------
   [INFO] BUILD SUCCESS
   [INFO]------------------------------------------------------------------------
   [INFO]Total time:28.298 s
   [INFO]Finished at:2018-01-10T23:36:19+08:00
   [INFO]FinalMemory:15M/163M
   [INFO]------------------------------------------------------------------------

5. Go to the Version Guide to find the latest SOFABoot version. In the folder from Step 1, find the new project folder, which is named after the `artifactId`. Then, in the main `pom.xml` file in the project's root directory, change the version number in the <parent> tag. The following example shows this process:

   

Project structure

The following sections explain the directory structures for the two types of SOFABoot projects.

• Web project archetype directory

• Core project archetype directory

This topic uses an example to help you understand the directory structure. The example project uses the following dependency information:

• groupId: com.alipay.sofa

• artifactId: APPNAME

Web project archetype directory

The Web project model creates two modules by default: endpoint and web.

• endpoint module: The service module for SOFAREST. It provides SOFAREST services to external clients.

• web module: The startup module that contains the `main` function and can be run directly. It also includes global configuration files, test modules, and static resources.

The following code shows the directory structure of a Web project created with a Maven command:

├── app
│├── endpoint
││├── pom.xml
││└── src
││└── main
││├── java
│││└── com
│││└── alipay
│││└── APPNAME
│││└── endpoint => SOFAREST practice code
│││├── constants
││││├──RestConstants.java
││││└──URLConstants.java
│││├── exception
││││├──CommonException.java
││││└──SofaRestExceptionHandler.java
│││├── facade
││││└──SampleRestFacade.java
│││├── filter
││││└──CommonContainerResponseFilter.java
│││├── impl
││││└──SampleRestFacadeRestImpl.java
│││├── model
││││└──DemoUserModel.java
│││└── response
│││├──AbstractFacadeResp.java
│││└──RestSampleFacadeResp.java
││└── resources
││└── META-INF
││└── APPNAME
││└── APPNAME-endpoint.xml
│└── web
│├── pom.xml
│└── src
│├── main
││├── java
│││└── com
│││└── alipay
│││└── APPNAME
│││└──Slite2WebSpringBootApplication.java => Startup function
││└── resources
││├── META-INF
│││└── APPNAME => Location for Spring configuration files. Place them in the specified APPNAME folder.
│││└── APPNAME-web.xml
││├── config => Configuration folder. For more information, see "Configuration Solutions".
│││└── application.properties => Application log configuration file
│││└── application-dev.properties
│││└── application-test.properties
││├── logback-spring.xml => Application log configuration file
││└──static=> Location for static pages of the web project
││└── index.html
│└── test => Application test module. It has a built-in Spring Boot starter for easy business testing.
│└── java
│└── com
│└── alipay
│└── APPNAME
│└── web
│└── test
│├──base
││└──AbstractTestBase.java
│└── usercases
│└──SofaRestServiceTest.java
└── pom.xml => Application's Maven configuration file

Core project archetype directory

The Core project model creates two modules by default, based on the application name: {APPNAME}-facade and {APPNAME}-service.

• facade module: Defines the application's interface dependency package.

• service module: The startup module that contains the `main` function and can be run directly. It also includes global configuration files and test modules. The following code shows the directory structure of a Core project created with a Maven command, using groupId=com.alipay.sofa and artifactId=APPNAME:

├── APPNAME-facade
│├── pom.xml
│└── src => Interface dependency package for distribution to other applications
│└── main
│└── java
│└── com
│└── alipay
│└── APPNAME
│└── facade
│└──SampleService.java
├── APPNAME-service
│├── pom.xml
│└── src
│├── main
││├── java
│││└── com
│││└── alipay
│││└── APPNAME
│││├──Slite2SpringBootAPPNAMEApplication.java => Startup function
│││└── service
│││└──SampleServiceImpl.java
││└── resources
││├── META-INF
│││└── APPNAME => Location for Spring configuration files. Place them in the specified APPNAME folder.
│││└── APPNAME-service.xml
││├── config => Configuration folder. For more information, see "Configuration Solutions".
│││├── application-dev.properties
│││├── application-test.properties
│││└── application.properties
││└── logback-spring.xml => Application log configuration file
│└── test => Application test module. It has a built-in Spring Boot starter for easy business testing.
│├── java
││└── com
││└── alipay
││└── APPNAME
││└── test
││├──base
│││└──AbstractTestBase.java
││└── usercases
││└──BeanTest.java
│└── resources
│└── test
│└── META-INF
│└── APPNAME
│└── test.xml
└── pom.xml => Application's Maven configuration file